JSON web token

The JSON web token (JWT) asset type lets you transmit authorization information between Matrix and a third-party system. The asset is available through the Connectors  JSON web token asset menu. All JWTs are signed using a secret and are encoded using the HMAC SHA256 standard.

JWT implementation

Read this section if you need to cross-check how the JWT implementation compares to a third-party JWT implementation.


Supported: HMAC SHA256
Not supported: RSA or ECDSA


Not supported

Payload visibility

Signed (publicly visible).

All payload information is visible in the payload when decoded. Do not put sensitive information such as passwords in the payload.

Understanding the JWT configuration items

Before you set up a JWT, you need to understand the three configuration items the asset requires:

  • Secret

  • Payload

  • Expiry time.

Make sure you have the required information for each configuration item before setting up a JWT asset in Matrix.


The secret is a shared key issued and used by the third-party service to verify that the token header and payload are authentic.

Check the third-party integration documentation for instructions on obtaining the correct secret.


Do not include sensitive information in the payload. The payload is signed using a shared secret but is not encrypted. Anyone can check the contents of the payload.

The payload sets the entity claims that get encoded within the token.

Entity claims are most commonly user credentials that the third-party service needs as part of the request.

The payload you send varies based on the service you are integrating with, but will almost certainly use one or more JWT public claims as documented on the IANA.org website.

Payloads use a standard JSON body with claims declared as key-value pairs.

  "sub": "1234567890",
  "name": "John Smith",
  "admin": true

In this example, sub is a registered claim, name is a public claim, and admin is a private claim specific to a third-party service.

Expiry Time

The expiry time populates the registered claim exp portion of the payload.

While you can leave the expiry time blank (unlimited expiry), this is not a good JWT security practice. A recommended expiry time is between five and 15 minutes.

The third-party service you are integrating with may also recommend an expiry time, which you should honour in your configuration.

Creating a JWT asset

You can create a JWT asset anywhere in the asset tree. The location you select determines the web path from which the token is available.

Follow these steps to create a JWT asset for authenticating to a third-party service:

  1. In the Matrix Admin view, select the asset you want to create the JWT asset beneath.

  2. Click New Child  Connectors  JSON Web Token to create the asset, and configure the name and link type.

  3. In the Secret field, supply the third-party service’s JWT secret.

  4. In the Payload field, specify the JSON claims required by the third-party service.

      "sub":         "%globals_user_attribute_username^json_encode%",
      "given_name":  "%globals_user_attribute_first_name^json_encode%",
      "family_name": "%globals_user_attribute_last_name^json_encode%",
      "admin":        %asset_has_write_access^eq:1:true:false%
  5. In the Expiry time field, specify an expiry time for the token.

Requesting the JWT

You can retrieve the generated JWT by sending an HTTP request to the web path of the JSON web token asset. Responses include a Content-Type of application/jwt and an appropriate HTTP Code.

HTTP Code Reason Value returned


A valid response from an authenticated user, that returns a valid generated JWT.



The JWT could not be generated due to a configuration error in the JSON Web Token asset.

Empty string


Failed to authenticate the user details.

Empty string

Testing the JWT asset

You can test whether the token is working correctly by testing it with a service like the jwt.io debugger.

  1. Right-click on the JWT asset and select Preview  In new window.

  2. Copy the JWT string displayed on the asset’s webpage.

  3. Visit the jwt.io debugger and decode the token.

  4. Verify the decoded token matches the configuration in Matrix.