All docs This doc

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: typos

JSON Web Token (JWT) is used to represent claims that are transferred between two parties such as the end-user and the backend.

A claim is an attribute of the user that is mapped to the underlying user store. It is encoded as a JavaScript Object Notation (JSON) object that is used as the payload of a JSON Web Signature (JWS) structure, or as the plain text of a JSON Web Encryption (JWE) structure. This enables claims to be digitally signed.

A set of claims is are called a dialect (e.g., The general format of a JWT is {token infor}.{claims list}.{signature}. The API implementation uses information such as logging, content filtering, and authentication/authorization that is stored in this token. The token is Base64-encoded and sent to the API implementation in a an HTTP header variable. The JWT is self-contained and is divided into three parts as the header, the payload, and the signature. For more information on JWT, see JSON Web Token (JWT) Overview.

To authenticate end-users, the API Manager passes attributes of the API invoker to the backend API implementation using JWT. In most production deployments, service calls go through the WSO2 API Manager or a proxy service. If you enable JWT generation in the API Manager, each API request will carry a JWT to the back-end service. When the request goes through the API manager, the JWT is appended as a transport header to the outgoing message. The back-end service fetches the JWT and retrieves the required information about the user, application, or token.


The above JWT token contains tthe the following information.

JWT Header : The header section  declares that the encoded object is a JSON Web Token (JWT) and the JWT is in plaintext, that is not signed using any encryption algorithm.


  • "iss" - The issuer of the JWT
  • "exp" - The token expiration time
  • "" - Subscriber to the API, usually the app developer
  • "" - Application through which API invocation is done 
  • "" - Context of the API
  • "" - API version
  • "" - Tier/price band for the subscription
  • "" - Enduser End-user of the app who's whose action invoked the API

Let's see how to enable and pass information in the JWT or completely alter the JWT generation logic in the WSO2 API Manager: 

Table of Contents

Configuring JWT

Before passing enduser end-user attributes, you enable and configure the JWT implementation in the <API-M_HOME>/repository/conf/api-manager.xml file. The relevant elements are described below. If you do not configure these elements, they take their default values.


ElementDescriptionDefault Value
Uncomment <EnableJWTGeneration> property and set this value to true to enable JWT.false
<JWTHeader> The name of the HTTP header to which the JWT is attached.X-JWT-Assertion

By default, the <ClaimsRetrieverImplClass> parameter is commented out in the api-manager.xml file. Enable it to add all user claims in the JWT token:

Code Block

By default, the following are encoded to the JWT:

  • subscriber Subscriber name
  • application Application name 
  • API context
  • API version
  • authorized Authorized resource owner name

In addition, you can also write your own class by extending the interface org.wso2.carbon.apimgt.impl.token.ClaimsRetriever and implementing the following methods of the interface:


void init() throws APIManagementException;

Used to perform initialization tasks. Is executed once, right before the very first request.

SortedMap<String,String> getClaims(String endUserName) throws APIManagementException;

Returns a sorted map of claims. The key of the map indicates the user attribute name and the value indicates the corresponding user attribute value. The order in which these keys and values are encoded depends on the ordering defined by the sorted map.

String getDialectURI(String endUserName);

The dialect URI to which the attribute names returned by the getClaims() method are appended to. For example,
if the getClaims method returns {, gender:male} and the getDialectURI() returns, the JWT will contain "":"male","":"" as part of the body.

The default implementation (org.wso2.carbon.apimgt.impl.token.DefaultClaimsRetriever) returns the user's attributes defined under the dialect URI and the JWT will also be encoded with the same dialect URI. The order of encoding the user's attributes is in the natural order of the attributes. If no value is specified, no additional claims will be encoded, except the 6 default attributes.


The dialect URI under which the user's claims are be looked for. Only works with the default value of the <ClaimsRetrieverImplClass> element defined above.

The JWT token contains all claims define in the <ConsumerDialectURI> element. The default value of this element is To get a list of users to be included in the JWT, simply uncomment this element after enabling the JWT. It will include all claims in to the JWT token.


Taken from the shared space:

The signing algorithm used to sign the JWT. The general format of the JWT is {token infor}.{claims list}.{signature}. When NONE is specified as the algorithm, signing is turned off and the JWT looks as {token infor}.{claims list} with two strings delimited by a period and a period at the end.

This element can have only two values - the default value, which is SHA256withRSA or NONE.


You can use TCPMon or API Gateway debug logs to capture JWT token headerwithenduserdetails header with end-user details. To enable gateway DEBUG logs for wire messages,

  1. Go to the <APIM_GATEWAY>/repository/conf directory and open the file with a text editor.
  2. Edit the entries for the two loggers as follows (remove the # in order to enable debug logs):