API Management versions 7.5.X and 7.6.X have reached end of support in November 2020.
Check out the latest version of the documentation.

JWT flow

A JSON Web Token (JWT) is a JSON-based security token encoding that enables identity and security information to be shared across security domains.

OAuth 2.0 JWT Flow

In the OAuth 2.0 JWT flow, the client application is assumed to be a confidential client that can store the client application's private key. The X.509 certificate that matches the client's private key must be registered in the Client Application Registry. The API Gateway uses this certificate to verify the signature of the JWT claim.

For more details on the OAuth 2.0 JWT flow, see:

Create a JWT bearer token

To create a JWT bearer token, perform the following steps:

  1. Construct a JWT header in the following format:
  2. {"alg":"RS256"}
  3. Base64url encode the JWT header, which results in the following:
  4. eyJhbGciOiJSUzI1NiJ9
  5. Create a JWT claims set, which conforms to the following rules:
    • Issuer (iss) must be the OAuth client_id, or the remote access application for which the developer registered their certificate.
    • Audience (aud) must match the value configured in the JWT filter. By default, this value is as follows:
    • http://apigateway/api/oauth/token
    • Validity (exp) must be the expiration time of the assertion, within five minutes, expressed as the number of seconds from 1970-01-01T0:0:0Z measured in UTC.
    • Time when assertion was issued (iat) is measured in seconds after 00:00:00 UTC, January 1, 1970.
    • JWT must be signed (using RSA SHA256). For more details, see:
    • JWT must conform with the general format rules specified in:
    • For example:
    • {
  6. Base64url encode the JWT claims set, resulting in:
  7. eyJpc3MiOiJTYW1wbGVDb25maWRlbnRpYWxBcHAiLCJhdWQiOiJodHRwOi8vYXBpc2VydmV
  8. Create a new string from the encoded JWT header from step 2, and the encoded JWT claims set from step 4, and append them as follows:
  9. Base64URLEncode(JWT Header) + . + Base64URLEncode(JWT Claims Set)
  10. This results in a string as follows:
  11. eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiAiU2FtcGxlQ29uZmlkZW50aWFsQXBwIiwgImF1ZCI6ICJodHRw
  12. Sign the resulting string in step 5 using SHA256 with RSA. The signature must then be base64url encoded. The signature is then concatenated with a . character to the end of the base64url-encoded representation of the input string. The result is the following JWT (line breaks added for clarity):
  13. {Base64url-encoded header}.
    {Base64url-encoded claim set}.
  14. This results in a string as follows:
  15. eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiAiU2FtcGxlQ29uZmlkZW50aWFsQXBwIiwgImF1ZCI6ICJodHR

Request an access token

The JWT bearer token should be sent in an HTTP POST to the token endpoint with the following parameters:

Parameter Description


Required. Must be set to urn:ietf:params:oauth:grant-type:jwt-bearer.


Required. Must be set to the JWT bearer token, base64url-encoded.


Optional. Expected return format. The default is json. Possible values are:

  • urlencoded
  • json
  • xml

The following is an example POST request:

POST /api/oauth/token HTTP/1.1
Content-Type:application/x-www-form-urlencoded; charset=UTF-8

Handle the response

API Gateway returns an access token if the JWT claim and access token request are properly formed, and the JWT has been signed by the private key matching the registered certificate for the client application in the Client Application Registry.

For example, a valid response is as follows:

HTTP/1.1 200 OK

Run the sample client

The following Jython sample creates and sends a JWT bearer token to the authorization server:


To run the sample, open a shell prompt at INSTALL_DIR/samples/scripts, and execute the following command:

> run oauth/jwt.py

Related Links