# JWT direct linking

JSON Web Token (JWT) is an open standard that defines a compact and self-contained method for securely transmitting information between two parties as a JSON object. JWTs are signed with private/public key pairs, which verify the integrity of the token and add an additional layer of security.

JSON Web Tokens authenticate users and provide verified access to applications and resources. Generate a JWT before implementing any Workato Embedding models.

JWT direct linking consists of the following steps:

  1. Generate a public/private key pair
  2. Install a direct link URL microservice
  3. Generate a JWT

# Prerequisites

The following information is required to implement JWT direct linking.

Private and public key pair
Required. The JWT token must be signed using a private key generated with the RS256 algorithm. Provide the public key to your Workato Success Representative. Workato uses the public key to verify the generated JWT tokens.
Workato Embedded vendor API key
Required. The Workato Embedded vendor API key is used to generate the JWT. Your Workato Success Representative shares this key with you securely after you provide them with your public key.
Customer team ID
Required. The customer team ID is the unique ID of the Workato Embedded customer account. From the UI, obtain the customer team ID by navigating to the Admin console and selecting the specific customer account. When selected, the customer team ID is present in the URL. Alternatively, fetch the customer team ID by calling our get customer account API.
Customer user ID
Optional. The customer user ID is the unique ID of an individual team member in the customer account. Include the customer user ID when the user's specific role must apply to the Workato session created. Fetch the customer user ID by calling our get customer account member API.
Origin URL
Required. The origin URL is the default domain where you embed the Workato iframe. In specific cases, you must include the origin URL in the payload of the JWT. Provide your Workato Success Representative with the origin URL.

Multiple API keys

The Workato Embedded vendor API key is different from the Workato API key obtained in the partner's Admin console. Use the Embedded vendor API key exclusively to generate JWTs and the Workato API key with Workato Embedded APIs.

# Step 1: Generate a private and public key pair

# Generate a private key

To generate the private key from scratch, use the following:

$ openssl genrsa -out private.key 2048
$ cat private.key



# Generate a public key

Then, extract the public key using the following:

$ openssl rsa -in private.key -pubout -out public.key
$ cat public.key


-----END PUBLIC KEY-----

# Convert keys to PEM format

If you used a different method to generate your public/private key pair, convert your keys to PEM format before sending them to Workato.

To convert from an SSH public key:

$ ssh-keygen -f key.pkcs -e -m pem > key.pem

# Step 2: Install a direct link URL generation microservice

The purpose of the direct link URL microservice is to automatically generate a JWT when needed to facilitate access to secure resources. Install a direct link URL microservice to your server.

The microservice must meet the following specifications:

  • The endpoint must require vendor authentication.

  • The microservice must accept the path to the Workato asset.

  • The microservice must generate a URL with the following structure:


# Example microservice:

import nanoid from 'nanoid';
import {sign} from 'jsonwebtoken';

function getToken(WorkatoEmbeddedapiKey, customerAccountId, privateKey) {
  return sign({
    sub: `${WorkatoEmbeddedapiKey}:${customerAccountId}`,
    jti: nanoid()
    algorithm: 'RS256'

# Step 3: JWT direct linking

# JWT structure

A JWT consists of a header, payload, and signature. In their compact form, JWT sections are separated by ..

The first part of the token is the header. The header usually consists of two parts: the type of token and the type of algorithm used to generate the signature.
The second part of the token is the payload, which contains the claims. Claims are statements about the user and additional data.
The final part of the token is the signature. Signatures verify the integrity of the claims.

# Generate a JWT

Generating a JWT consists of the following steps:

  1. Configure the header
  2. Configure the payload
  3. Sign the token

Step 1: Configure the header

Set the alg claim to RS256, the algorithm used to generate the signature.
Set the typ claim to JWT, the type of token used.


  "alg": "RS256",
  "typ": "JWT"

Step 2: Configure the payload

Set the sub claim to:


Visit the Prerequisites section for detailed instructions on obtaining the Workato Embedded vendor API key, customer team ID, and customer user ID.

Set the iat claim to the current time in epoch.
Set the jti claim to a globally unique value. Use the value only one time in a 10-minute duration.
The origin claim is required when the connection iframe is embedded in two or more origins.

Mulitiple origins

If you are embedding the Connection Widget in multiple domains, you must configure the origin URL in each customer account. To override the origin URL in an individual account, go to the Admin console > manage customers, and access the relevant customer account. Access the settings menu and update the origin URL.


  "sub": "911672h4203fae7ffbe2eca1bbcaa79cc8c47af5377a6c6240:303363:313646",
  "jti": "3oay2t2kntGbxr1yhSINn",
  "origin": "http://www.acme.com"

See more JWT microservice examples. (opens new window)


Step 3: Sign the JWT

Sign the JWT with your private key generated with the RS256 algorithm in Step 1. The private key must match the public key previously provided to Workato.