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.


Scopes enable fine-grained access control to API resources based on user roles. 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.

How scopes work

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


Code Block
<ams:fault xmlns:ams="">
      <ams:message>The access token does not allow you to access the requested resource</ams:message>
      <ams:description>Access failure for API: /orgnews, version: 1.0.0 with key: eb51eff0b4d85cda1eb1d312c5b6a3b8

Applying a scope

You apply scopes to an API resource at the time the API is created or modified. In the API Publisher, click the API -> Add menu (to add a new API) or the Edit link next to an existing API. Then, navigate to the Manage tab and scroll down to see the Add Scopes button under Resources. A screen such as the following appears:



Tip: When you generate access tokens to APIs protected by scope/s, a Select Scopes button is displayed in the My Subscriptions page for you to select the scope/s first and then generate the token to it.

Scope whitelisting

A scope is not always used for controlling access to a resource. You can also use it to simply mark an access token. Such scopes do not have to have roles associated with them. Skipping role validation for scopes is called scope whitelisting.

To whitelist a scope, add it under the APIKeyValidation element and restart the server. For example,

Code Block

Next, invoke the Token API to get a token for the scope that you whitelisted. For example,

Code Block
curl -k -d "grant_type=password&username=admin&password=admin&scope=some_random_scope" -H "Authorization: Basic WmRFUFBvZmZwYVFnR25ScG5iZldtcUtSS3IwYTpSaG5ocEVJYUVCMEN3T1FReWpiZTJwaDBzc1Vh, Content-Type: application/x-www-form-urlencoded"

Note that the issued token has the scope you requested:

Code Block


API templates

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.