Child pages
  • Generate Access Tokens to Authenticate APIs

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  • Application Access Tokens : Tokens to authenticate an application, which is a logical collection of APIs. You to access all APIs associated with an application using a single token, and also subscribe multiple times to a single API with different SLA levels. Application access tokens leverage OAuth2 to provide simple key management.
  • User Access Tokens : Tokens to authenticate the final user of an API, such as the final user of a mobile application deployed on different devices. User access tokens allow users to invoke an API even from a third-party application like a mobile app.

The sections below show how to generate and renew each type of access token:


  1. Log in to the API Store.
  2. Click My Subscriptions from the menu bar at the top of the screen. The Subscriptions page opens, using which you can generate a production key and/or a sandbox key for testing purpose.
    Image Removed

    The two inputs mean the following:

    Allowed Domains

    The domains from which requests are allowed to the APIs. Leave empty or enter "ALL" to allow all domains.

    Whenever an API call happens, the Gateway checks if the request originated from an allowed domain and grants access accordingly. This ensures that clients from a restricted domain cannot access an API even if an application key is stolen (when the key is placed in client-side JS code).

    When the client makes a request to an API that is only allowed to some domains, the request message must have an HTTP header to specify its domain name. Sending this header is mandatory only if the API is restricted to certain domains. An admin can configure this header name using <ClientDomainHeader> element under the <APIGateway> element in <APIM_HOME>/repository/conf/api-manager.xml. For example, if the file contains <ClientDomainHeader>domain</ClientDomainHeader>, then the API invocation request must contain an HTTP header called domain with values as shown in the example below:
    curl -v -H "Authorization: Bearer xxx" -H "domain:" http://localhost:8280/twitter/1.0.0/search.atom?q=cat

    Token ValidityText AreaThe period after which the token will be expired after generation. A negative value ensures that the token will never expire.


  1. .


After an access token is generated, users sometimes want to renew the old token due to expiration or security concerns. API Consumers can re-generate/refresh access tokens in the following ways.


By default, access tokens, consumer keys and consumer secrets are not encrypted in the database. An admin can enable encryption as follows:

  • Set the value of the <EncryptPersistedTokens> to true inside the <APIKeyManager> section of the <APIM_HOME>/repository/conf/api-manager.xml file.

  • Change the <TokenPersistenceProcessor> to org.wso2.carbon.identity.oauth.tokenprocessor.EncryptionDecryptionPersistenceProcessor in the <APIM_HOME>/repository/conf/identity.xml file.

If you want to keep authorization headers in massages that are going out of the API Gateway, an admin can go to <API Gateway Node>/repository/conf/api-manager.xml file, uncomment the <RemoveOAuthHeadersFromOutMessage> element, set its value to false and then restart the server to apply the changes.

When an application access token expires, consumers can refresh the token you renew it by logging into the API Store, selecting the My Subscriptions link at the top of the screen, menu and and clicking Re-generate. You can also specify a token expiration time for the application access token or change its allowed domains. Set to a negative value to ensure that the token never expires.

Image Removed


To renew a user token, issue a REST call to WSO2 Login API through a REST client. For more information, see Renew User Tokens.

You can configure the API Manager instances to store access tokens in different tables according to their user store domain. This is referred to as user token partitioning and it ensures better security when there are multiple user stores in the system. For configuration details, see user token partitioning.


Access Tokens have a expiration time, which is set to 60 minutes by default.

  • To change the default expiration time of application access tokens,
    • Change the value of <ApplicationAccessTokenDefaultValidityPeriod> element in <APIM_HOME>/repository/conf/identity.xml file. Set to a negative value to ensure that the token never expires.
    • Alternatively, you can set a default expiration time through the UI when generating/regenerating the application access token. This is explained in previous sections.
  • Similarly, to change the default expiration time of user access tokens, edit the value of <UserAccessTokenDefaultValidityPeriod> element in identity.xml file.

Also see Configuring Caching for several caching options available to optimize key validation.

After subscribing to an API and generating a key to access it, the next step is to invoke the API through the Gateway using the steps given in section Invoking APIs.

Image Added