Access Tokens

Access tokens are string fields that identify the client of a Callable Recipe. The token value is a secret that is shared between a client and the Workato server. A token is passed to the API in an authorization header. The header must have a valid value in order for the call to succeed.

Workato supports two token formats: Auth Token and JSON Web Token (JWT).

Auth Tokens

An Auth Token is automatically generated when an Access Profile is created. It is a long string.

The Access Profile screen displays this string (but masked for security reasons) after a Profile is created. The auth token can be copied to the clipboard.

The Refresh button will generate a new Auth Token value and invalidates any previous value.

Auth Token for an Access profile Auth Token for an Access profile

When calling an endpoint, the Auth Token value is passed as the value of the API-Token header.

JWT Tokens

For additional security, clients can now make use of JSON Web Tokens (JWT). These is a standard RFC 7159 method for web authentication. JWT tokens are signed using a secret or key selected by the client.

When JWT is selected in the Access Profile screen, there are two additional field values to select. One is the signing method and the other is a secret or key field.

Workato supports two signing methods: HMAC and RSA. HMAC uses a symmetric shared secret (client and server have the same secret). RSA uses an asymmetric key pair (client has a private key and shared the public key with the server). HMAC uses a 256-bit secret value.

If you select HMAC, you will see the following fields in the Access Profile screen:

JWT Token Configuration JWT Token Configuration

The shared secret can be any value that you select, but for best security, it should be a long value generated by a secure random number generator. If you have OpenSSL, you can generate such a secret with the command:

openssl rand -base64 32

Paste the secret value into the JWT HMAC secret field.

If you select RSA then you must have an RSA public key/certificate and a corresponding RSA private key. One way to generate this is by using OpenSSH:

ssh-keygen -t rsa

This will generate two files, one for the private key (no extension) and one for the public key (.pub extension). A typical public key file might look like this:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC4O6vRGXTkXWQ4yjj6baC7xAlrJPagWQ1WgI7RBUfk5PRPyD88Lp1vqe0CqshOIEeIVca3mD+W0YtJGlu4IaFh2gIC0W2lQY+3yXkzw2IQvnK1jjzxLJ6Dho7Vh3kLVqlmDB0ABdFhoU+vZf19AnLMqGhmu81xXoutK89MJAfvGFWbZ/zfM/yl9aqTOVrEJFpUxloL2IY/EAiUqblRTH5KWtimetEPF8VG3hu/YeU/5/CzPGZaLKUOcO3k0A6a6iIA2ruV180QN0FmgrCUsQ6oA6vWZsY1LuJm3bnLv7KJApR+WYqp7OCMlhk67N7zxkbZqNb2+eyUCx7E2SFCjFkR jdart@bear

The public key needs to be pasted into the Public Key field in the Access Profile screen.

Generating JWT Tokens

A JWT token can encapsulate several pieces of information that the client communicates to the server. For Workato, the essential information is the Workato access key and the name of the user. These should be placed in a JSON structure similar to the following:

{
  "sub": "d4aee74e131926682043395edecaf377765fae48e56e232cb295af475b314545",
  "name": "John Doe"
}

Here sub is the Auth token that is obtainable from the Access Profile screen in Workato, and name is the name of the client.

The JWT token is a signed representation of the JSON structure. You can generate a JWT token using the tools at JWT.IO.

With JWT, the client is responsible for generating and packaging a token in the correct format. An online tool is available at JWT.IO to facilitate this. The JSON format text mentioned above should be pasted or typed into the "payload" field on the "Decoded" side of the tool. In addition, they will paste in the private key (RSA) or secret string (HMAC) in the "Verify Signature" section. The signed and encoded key then appears on the right-hand side in the "Encoded" section.

The two standard algorithms Workato supports are HS256 (aka HMAC) and RS256 (aka RSA).

For example, generation of an HMAC JWT might look like this:

JWT Generation JWT Generation

Invoking APIs secured with JWT

Testing an API endpoint

Once the JWT token is generated, clients can test the APIs by visiting the API group URL. Click on Copy client URL in the client screen as shown in the image below. You can provide your client with this URL.

Copy client URL Copy the client URL

Next, select a collection in the next screen. To test an API endpoint within a collection, click on the toggle for Authentication method and token and select JSON web token (JWT). Paste the JWT token here and set the token.

Select JWT Setting the JWT token

After setting the token, choose on one of the endpoints and provide valid values for the required parameters. Click on Test at the bottom of the page to test the API endpoint. The test should return a 200 response code and the expected response body.

Select JWT 200 response code and response body

Calling an API endpoint

The encoded and signed token is passed to the Workato API in the header (see Calling APIs). The access token is sent in the Authorization header with the Bearer authentication scheme.

  1. The example below shows how the token is used in Postman: Postman test Example of a JWT token used in Postman

  2. The example below shows how the token is used in a curl request:

    curl -XGET \
    -H 'Authorization: Bearer ayJhbGciOiJIUzI1NakIKjkJFVCJ9.eyJzdWIiOiI4OJSIFMLLdkZTY0ZWZkNDY1MTcyMjk2MDA2ZTlmNDEwNGEzOGJmMDAzZTk0YmYyYzRiMzhjYzg3ZDgwYjU0ODk1IiwibmFtZSI6os9fvaG4gRG9lIn0.D_ZHmYZkbRAFQeL' \
    'https://apim.workato.com/api-endpoints-v1/call?email=john-doe%40acme.com'
    

results matching ""

    No results matching ""