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

All docs This doc

Versions Compared


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


Table of Content Zone

API Publisher

API development is usually done by someone who understands the technical aspects of the API, interfaces, documentation, versions etc., while API management is typically carried out by someone who understands the business aspects of the APIs. In most business environments, API development is a responsibility that is distinct from API publication and management. 

WSO2 API Manager provides a simple Web interface called WSO2 API Publisher for API development and management. It is a structured GUI designed for API creators to develop, document, scale and version APIs, while also facilitating more API management-related tasks such as publishing API, monetization, analyzing statistics, and promoting. 

The API Publisher URL is https: //<YourHostName>:9443/publisher  and it is accessible on HTTPS only. The default credentials are admin/admin.

The diagram below shows the common lifecycle activities of an API developer/manager:

API Store (Developer Portal)

The API Store Web application provides a collaborative interface for API publishers to host and advertise their APIs and for API consumers to self register, discover, evaluate, subscribe to and use secured, protected, authenticated APIs.

The API Store URL is https: //<YourHostName>:9443/store  and it is accessible on HTTPS only. The default credentials are admin/admin.

The diagram below shows common API consumer lifecycle activities:

API Gateway

A runtime, backend component (an API proxy) developed using WSO2 ESB. API Gateway secures, protects, manages, and scales API calls. It intercepts API requests, applies policies such as throttling and security using handlers, and manages API statistics. Upon validation of a policy, the Gateway passes web service calls to the actual backend. If the service call is a token request, the Gateway passes it directly to the Key Manager

When WSO2 API Manager is running, you can access the Gateway using the following URL: https://localhost:9443/carbon. You integrate a monitoring and analytics component to the API Manager by configuring WSO2 API Manager Analytics. This component provides reports, statistics and graphs on the APIs deployed in WSO2 API Manager. You can then configure alerts to monitor these APIs and detect unusual activity, manage locations via geo location statistics and, carry out detailed analysis of the logs.


Although the API Gateway contains ESB features, it is recommended not to use it for ESB-specific tasks. Use it only for Gateway functionality related to API invocations. For example, if you want to call external services like SAP, use a separate ESB cluster for that purpose.

Key Manager

Manages all clients, security and access token-related operations. The Gateway connects with the Key Manager to check the validity of OAuth tokens, subscriptions and API invocations. When a subscriber creates an application and generates an access token to the application using the API Store, the Store makes a call to the API Gateway, which in turn connects with the Key Manager to create an OAuth client and obtain an access token. Similarly, to validate a token, the API Gateway calls the Key Manager, which fetches and validates the token details from the database.

The Key Manager also provides a token API to generate OAuth tokens that can be accessed via the Gateway. All tokens used for validation are based on the OAuth 2.0.0 protocol. Secure authorization of APIs is provided by the OAuth 2.0 standard for key management. The API Gateway supports API authentication with OAuth 2.0, and enables IT organizations to enforce rate limits and throttling policies.

The Key Manager properly decouples the operations for creating OAuth applications and validating access tokens so that you can even plug in a third party-authorization server for key validations.

You can avoid making the Gateway connect with the Key Manager every time it receives an API invocation call, by enabling API Gateway caching. When caching is not enabled, a verification call happens every time the Gateway receives an API invocation call. For this verification, the Gateway passes an access token, the API, and API version to the Key Manager. Communication between the API Gateway and the Key Manager happens in either of the following ways:  

  • Through a Web service call
  • Through a Thrift call (Thrift is the default communication protocol and is much faster than SOAP over HTTP)

If your setup has a cluster of multiple Key Manager nodes that are fronted by a load balancer that does not support Thrift, change the key management protocol from Thrift to WSClient using the <KeyValidatorClientType> element in the <API-M_HOME>/repository/conf/api-manager.xml file. Thrift uses TCP load balancing.

In a typical production environment, you can configure one of the following setups:

Traffic Manager

The Traffic Manager helps users to regulate API traffic, make APIs and applications available to consumers at different service levels, and secure APIs against security attacks. The Traffic Manager features a dynamic throttling engine to process throttling policies in real-time, including rate limiting of API requests. For more information, see Working with Throttling.


Additionally, monitoring and analytics are provided by the analytics component, WSO2 API Manager Analytics. This component provides a host of statistical graphs , an and an  alerting mechanism on pre-determined events and a log analyzer. For more information, see Working with Analytics


For a detailed description of handlers and how to write a custom handler, see Writing Custom Handlers.


Users and roles

The API Manager offers four distinct community roles that are applicable to most enterprises:

  • Admin: the API management provider who hosts and manages the  API Gateway . S/he is responsible for creating user roles in the system, assign them roles, managing databases, security etc. The Admin role is available by default with the credentials admin/admin.
  • Creator: a creator is a person in a technical role who understands the technical aspects of the API (interfaces, documentation, versions etc.) and uses the API publisher to provision APIs into the API store. The creator uses the API Store to consult ratings and feedback provided by API users. Creator can add APIs to the store but cannot manage their lifecycle.
  • Publisher: a publisher manages a set of APIs across the enterprise or business unit and controls the API lifecycle, subscriptions and monetization aspects. The publisher is also interested in usage patterns for APIs and has access to all API statistics.
  • Subscriber: a subscriber uses the API store to discover APIs, read the documentation and forums, rate/comment on the APIs, subscribes to APIs, obtain access tokens and invoke the APIs.


The API Manager comes with a pre-created default application, which allows unlimited access by default. You can also create your own applications.


Callback URL

A callback URL is a URL that sends a callback to a specific server or program soon after your application request is sent. The callback URL is specified when generating or re-generating production or sandbox keys for an application. You can either provide a single application callback URL or a RegEx pattern as the callback URL. You use a RegEx pattern as the callback URL when you need to specify multiple callback URLs for an application.

For example, consider a situation where you have two (2) service providers that need to use the same application that have the following callback URLs:

  • https://testapp:8000/callback

In this instance, your callback URL should have the following RegEx pattern:



You can configure any RegEx pattern to match the callback URLs that you need to register with the application. However, it is mandatory to have the prefix regexp= before the pattern.


Access tokens

An access token is a simple string that is passed as an HTTP header of a request. For example, "Authorization: Bearer NtBQkXoKElu0H1a1fQ0DWfo6IX4a." Access tokens authenticate API users and applications, and ensure better security (e.g., prevent certain types of DoS attacks. Note that DoS attacks made to the key manager with random access tokens can not be prevented. DoS attacks with the same fake acess access token can affect the Gateway as well ). If a token that is passed with a request is invalid, the request is discarded at the first stage of processing. Access tokens work equally well for SOAP and REST calls.

For more information on different types of access tokens and how to generate them, see Working with Access Tokens.


Throttling Throttling tiers

Throttling allows you to limit the number of successful hits to an API during a given period of time, typically in cases such as the following:

  • To protect your APIs from common types of security attacks such as certain types of Denial Denial of Service (DoS) attacks
  • To regulate traffic according to infrastructure availability
  • To make an API, application, or a resource available to a consumer at different levels of service, usually for monetization purposes


You can define throttling at the API, application, and resource levels. The final request limit granted to a given user on a given API is ultimately defined by the consolidated output of all throttling tiers together. For more information about throttling, see Setting Throttling Limits.


Multi tenanted API management

A tenant in WSO2 API Manager is a separate business level entity, such as an organizational unit or a department. Muli tenancy enables such organizational units/departments to share the same API Manager deployment and the respective resources, but function individually with an isolated view of the deployment. A tenant does not need to be aware of the other tenants in the system as by design the Multitenancy creates an isolated space for each tenant, although they are sharing the same deployment. 


Subscription availability has three options. Those options are as follows:

  • Available to current Tenant Only
  • Available to All the Tenants
  • Available to Specific Tenants

See the next section on API Visibility and Subscription for more details on each category.

Additionally, its possible to configure a secondary userstore per tenant as well. For more information, see Configuring Secondary Userstores


API visibility and subscription Availability

API visibility

Visibility settings prevent certain user roles from viewing and modifying APIs created by another user role.

  • Public: The API is visible to all users who are registered and anonymous (who use APIs without login to the store, for example testing and demonstration), and can be advertised in multiple stores (central and non-WSO2 stores).
  • Restricted by Roles: The API is visible to it's tenant domain and only to the user roles that you specify. You should provide the roles separated by commas in the UI or as a cURL parameter when creating or editing the API. 

  • Visible to my domain: The API is visible to all users who are registered to the API's tenant domain. This option is available only in a multi-tenanted environment . It's not applicable when there is only one active tenant (super tenant) in the system.

Given below is how visibility levels work for users in different roles:


API visiblity level specified in the UIAPI visiblity level specified in the REST API
Publicpublic i.e. "visibility": "PUBLIC"
Visible to my domainprivate i.e. "visibility": "PRIVATE"
Restricted by rolesrestricted i.e. "visibility" :"RESTRICTED" , visibleRoles :["role1","role2", "role3"]

Subscription availability

The subscription availability option has three values as follows. You can set subscription availability to an API through the API Publisher's Manage tab. 


The diagram below depicts the relationship between the API's visibility and subscription availability:

 Image Modified

Refer the article  Multi Tenant API Management with WSO2 API Manager for examples and real world usage of the above concepts.


API documentation visibility


Then, log in to the API Publisher, click the Docs tab of an API, and click Add New Document to see a new drop-down list added to select visibility from:

Image Modified 

You set visibility in the following ways:


The diagram below shows a resource by the name CheckPhoneNumber added with four HTTP methods.

Image Modified 

 When you add resources to an API, you define a URL pattern and HTTP methods. A resource can also have a list of OAuth scopes.

URL Pattern

A URL pattern can be one of the following types:

  • As a url-mapping. E.g., /state/town/*
  • As a uri-template. E.g., /{state}/{town}

The terms url-mapping and uri-template come from synapse configuration language. When an API is published in the API Publisher, a corresponding XML definition is created in the API Gateway. This XML file has a dedicated section for defining resources. See examples below:

Code Block
<resource methods="POST GET" url-mapping="/state/town/*">
<resource methods="POST GET" uri-template="/{state}/{town}">

url-mapping performs a one-to-one mapping with the request URL, whereas the uri-template performs a pattern matching.

Parametrizing the URL allows the API Manager to map the incoming requests to the defined resource templates based on the message content and request URI. Once a uri-template is matched, the parameters in the template are populated appropriately. As per the above example, a request made to http://gatewa_host:gateway_port/api/v1/texas/houston sets the value of state to texas and the value of town to houston. You can use these parameters within the synapse configuration for various purposes and gain access to these property values through the uri.var.provincestate and uri.var.districttown properties. For more information on how to use these properties, see Introduction to REST API and the HTTP Endpoint of the WSO2 ESB documentation.

Also see on URI templates.


The default in-sequence, out-sequence and fault sequences are generated when the API is published.


HTTP methods

HTTP methods specify the desired action to be performed on an API's resource. You can select multiple methods from GET, POST, PUT, DELETE, PATCH, HEAD and OPTIONS. A method has attributes such as an OAuth scope, authentication type, response content type, parameters etc. as the diagram below shows:

Image Modified 
The main attributes of a method are described below:

OAuth scopes define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method.
Response content typeYou can Authentication type

The authentication type can be one of the following:

  • None: No authentication is applied and the API Gateway skips the authentication process.
  • Application: Authentication is done by the application. The resource accepts application access tokens.
  • Application User: Authentication is done by the application user. The resource accepts user access tokensuse the Produces attribute to document in what type the backend sends the response back to the API Manager. Note that this attribute does not do any message type conversion, it is only used as a way of letting the user know the type of response they will receive. You can define the response content type in the Design tab when creating an API.
    ParametersParameters of an HTTP method are analogous to arguments of a function in an object-oriented programming language. A resource's parameters are cached in the resource cache at the API Gateway. You can define the parameters in the Design tab when creating an API.

    Image Added

    Parameters of an HTTP method are analogous to arguments of a function in an object-oriented programming language. A resource's parameters are cached in the resource cache at the API Gateway
    OAuth scopes

    You can define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method. You can define the OAuth scopes in the Manage tab when creating an API as shown above.

    Authentication typeParameters

    You can set the response content type by navigating to the Manage tab, when creating an API, and select the corresponding authentication from the "Application & Application user" drop-down list, which corresponds to the respective resource.

    The authentication type can be one of the following:

    • None: You can select this option to create a non-authenticated API. This will remove the authentication requirements for regular managed APIs, so that the API Gateway skips the authentication process. This is useful in instances when you want to still have the API listed on the API Store home screen and/or when you want to disable authentication requirement for individual resources of an API.

    • Application: The authentication is done by the application and the resource accepts application access tokens. Therefore, if you select this option, the API will require OAuth tokens generated with a client grant type that produces tokens specific to the subscription, but not the end-users. Therefore, if there is a web or mobile application that has subscribed to this API and it has multiple end-users, then they will all share the same token and the API backend will not know which end-user invoked the API.

    • Application User: Authentication is done by the application user and the resource accepts user access tokens. Therefore, if you select this option, the API accepts the OAuth tokens that are generated with the password grant type. These tokens are specific to the end-user, because they not just require the application key, but also the end-user’s username and password. In this case, each end-user gets their own OAuth tokens even though they are using the same API subscription. The API Gateway then generates a JWT token and uses it to pass application and user information to the API backend.
    • Application and Application User: Both application and application
    user  level
    • user level authentication is applied. Thereby, both kinds of tokens are acceptable by the API.
      Note that if you select this option in the UI, it appears as Any in the API Manager's internal data storage and data representation, and Any will appear in the response messages as well
    • .

    Note that for the resources that have HTTP verbs (GET, POST etc.) requiring authentication (i.e., Auth Type is not NONE), set None as the Auth type of OPTIONS . This is to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway.

    (The above screenshot shows this).  

    The auth type is cached in the API Manager for better performance. If you change the auth type through the UI, it takes about 15 minutes to refresh the cache. During that time, the server returns

    the old auth type from the cache. If you want the changes to be reflected immediately, please restart the server after changing the auth type.
    Response content typeYou can use this attribute to document in what type the backend sends the response back to the API Manager. Note that this attribute doesn't do any message type conversion, but used simply as a way of letting the user know what type the response will be.

    the old auth type from the cache. If you want the changes to be reflected immediately, please restart the server after changing the auth type.


    Cross-origin resource sharing

    Cross-origin resource sharing ( CORS ) is a mechanism that allows restricted resources (e.g., fonts, JavaScript) of a Web page to a Web page to be requested from another domain outside another domain outside the domain from which the resource originated.

    The Swagger API Console that is integrated in the API Manager runs as a JavaScript client in the API Store and makes calls from the Store to the API Gateway. Therefore, if you have the API Store and Gateway running on different ports, enable CORS between them. 


    The elements are described below:

    HeaderDescriptionSample values
    Access-Control-Allow-OriginDetermines whether a resource can be shared with the resource of a given origin. The API Gateway validates the origin request header value against the list of origins defined under the Access Control Allow Origins configuration(this can be All Allow Origins or a specific value like localhost). If the host is in the allowed origin list, it will be set as the Access-Control-Allow-Origin response header in the response.All Allow Origins(*), localhost
    Access-Control-Allow-HeadersDetermines, as part of the response to a preflight request (a request that checks to see if the CORS protocol is understood), which header field names can be used during the actual request. The gateway will set the header values defined under Access Control Allow Headers configurations.authorization, Access-Control-Allow-Origin, Content-type, SOAPAction
    Access-Control-Allow-MethodsThis header specifies the method(s) allowed when accessing the resource in response to a preflight request. Required methods can be defined under the Access Control Allow Method configuration.GET, PUT, POST, DELETE, PATCH, OPTIONS
    Access-Control-Allow-CredentialsDetermines whether or not the response to the request can be exposed to the page. It can be exposed when the header value is true. The header value can be set to true/false by enabling/disabling the Access Control Allow Credentials configuration.true, false


    Code Block
       <handler class=""/>


    OAuth OAuth scopes

    Scopes enable fine-grained access control to API resources based on user roles. You  You define scopes to an API's resources. When a user invokes the API, his/her OAuth 2 bearer token cannot grant access to any API resource beyond its associated scopes.


    OAuth provides a method for clients to access a protected resource on behalf of a resource owner. OAuth 2 bearer token is a security token that any party in possession of it can use the token for authentication. Refer OAuth 2.0 Specification of Bearer Token Usage for more information.

    How scopes work

    To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API: 



    Tip: When you generate access tokens for applications with APIs protected by scope/s in the API Store, a Scopes drop down list is displayed in the  the  Production Keys tab of the application, where you can select the scope/s after the token is generated.


    For a complete example, please refer the article : An Overview of Scope Management with WSO2 API Manager


    A scope is not always used for controlling access to a resource. You can also use it to simply mark an access token. There are scopes that cannot be associated to roles (e.g., openid, device_). Such  Such scopes do not have to have roles associated with them. Skipping role validation for scopes is called scope whitelisting.


    An API template is its XML representation, which is saved in <APIM_HOME>/repository/resources/api_templates/velocity_template.xml file. This file comes with the API Manager by default. You can edit this default template to change the synapse configuration of all APIs that are created.

    If you are using a distributed API Manager setup (i.e., Publisher, Store, Gateway and Key Manager components are running on separate JVMs), edit the template in the Publisher node.



    An endpoint is a specific destination for a message such as an address, WSDL, a failover group, a load-balance group etc.