This documentation is for WSO2 API Manager 1.9.0. View documentation for the latest release.

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Reviewed and updated.



Apart from response caching, all the other caches are enabled by product. When the WSO2 API Manager components are clustered, they work as distributed caches. This means that a change done by one node is visible to another node in the cluster.

API Gateway cache

When c aching caching is enabled at the Gateway and Gateway and a request hits the Gateway, it first populates the cached entry for a given token. If a cache entry does not exist in cache, it calls the Key Manager server. This process is carried out using Web service calls. When the Key Manager server returns the validation information, it gets stored in the Gateway. When API Gateway caching is enabled, as the API Gateway issues a Web service call to the Key Manager server only if it does not have a cache entry, this method reduces the number of Web service calls to the Key Manager server. Therefore, it is faster than the alternative method.


The following caches are available: 

Table of Contents

Key cache

In a typical WSO2 API Manager deployment, the Gateway is deployed in a DMZ, while the Key Manager is in MZ. By default, caching is enabled at the Gateway. If you do not like to cache token related information in a leniently secured zone, you can do that on the Key Manager side. In  In this method, the Gateway issues a Web service call to the Key Manager server for every API call that hits the API Gateway. If the cache entry is available in the Key Manager server, it is returned to the Gateway. Otherwise, the database will be checked for the validity of the token.


  1. Disable caching at the API Gateway.
    Add the following entry under the <APIGateway> element in the <APIM_HOME>/repository/conf/api-manager.xml file.

    Code Block
  2. Enable the Key Manager cache.
    Add the following entry under the < APIKeyValidator> element in the in the api-manager.xml file.

    Code Block

JWT cache

You need to use JSON Web Tokens (JWT) when you need to pass certain end-user attributed to the back-end. If you enable  JWT generation, the token is generated in the Key Manager server for each validation information object and is sent as part of the key validation response. Usually, the JWT also gets cached with the validation information object, but you may want to generate JWTs for each call, and you can do this by enabling JWT caching at Key Manager server.

  1. Enable JWT caching at Key Manager server as follows:
    Add the following entry under the <APIKeyValidator> element in the <APIM_HOME>/repository/conf/api-manager.xml  file file.

    Code Block
    • You must disable caching at the Key Manager server side in order to generate JWTs for each call.
    • Disabling the JWT cache only works if you have enabled the Key Manager cache, which is disabled by default.
  2. Enable token generation.
    Set the following entry to true at the root level of the api-manager.xml file.

    Code Block

OAuth cache

The OAuth token is saved in this cache, which is enabled by default. Whenever a new OAuth token is generated, it is saved in this cache to prevent constant database calls. Unless  Unless an OAuth expires or is revoked, the same token is sent back for the same user. Therefore, you do not need to change this cached token most of the time. 

Response cache

The WSO2 API Manager uses WSO2 ESB's cache mediator to cache response messages per for each API. Caching improves performance, because the backend back-end server does not have to process the same data for a request multiple times. To You need to set an appropriate timeout period to offset the risk of stale data in the cache, you set an appropriate timeout period.

You enable response caching when creating a new API or editing an existing one API using the API Publisher UI. Go to the API Publisher and click on the Add API menu (to create a new API) or the Edit link associated with an existing API. Then, navigate to the Manage tab where you find the response caching section. You can set it the Response Caching field to Enabled and give a timeout value. This enables the default response caching settings.

Image Modified

To change the default response caching settings, edit the following cache mediator properties in <APIM_HOME>/repository/resources/api_templates/velocity_template.xml file:  

  • true: specifies that the mediator instance is a response collection instance
  • false: specifies that the mediator instance is a cache serving instance

max MessageSize  

Specifies the maximum size of a message to be cached in bytes. An This is an optional attribute , with the and its default value is set to unlimited.
maxSize Defines the maximum number of elements to be cached.


Defines the hash generator class.

When caching response messages, a hash value is generated based on the request's URI, transport headers, and the payload (if available). WSO2 has a default REQUESTHASHGenerator class written to generate the hash value. See Click here to view the sample here.

If you want to change this default implementation (for example, to exclude certain headers), you can write a new hash generator implementation by extending the REQUESTHASHGenerator and overriding its getDigest() method. Once done, add the new class as the hashGenerator attribute of the <cache> element in the velocity_template.xml file.

API Store cache

The API Store has several caches to reduce the page-load times and increase its responsiveness when multiple users access it simultaneously.

  • Tag cache: This cache saves the API's tags after they have been retrieved from registry. If your APIs and associated tags change frequently, it is recommended to configure a smaller cache refresh time (in milliseconds). This cache disabled by default. To enable it, uncomment the <TagCacheDuration> element in the <APIM_HOME>/repository/conf/api-manager.xml file. 

  • Recently-added-API cache : This cache saves the five most recently added APIs. It is disabled by default. If  If you have multiple API modifications during a short time period, it is recommended to not enable this cache. To enable it, set the <EnableRecentlyAddedAPICache> to true in the <APIM_HOME>/repository/conf/api-manager.xml file.