This documentation is a work in progress and will be released with the WSO2 API Manager 3.0.0 GA release.
Scope Registration and Management - API Manager 3.0.0 - WSO2 Documentation

All docs This doc
Skip to end of metadata
Go to start of metadata

Before you begin:

Scopes enable fine-grained access control to API resources based on user roles. You can define scopes to API resources. When users invokes the API, their 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:

Assume there are two users Chris and Alex. Chris is assigned the employee role. Alex is assigned both employee and manager roles.

Chris requests a token through the Token API as grant_type=password&username=chris&password=xxxx&scope=news_read news_write. However, as Chris is not in the manager role, only a token bearing the news_read scope is granted. The response from the Token API will be similar to the following:


Next, Alex requests a token as grant_type=password&username=alex&password=alex123&scope=news_read news_write . As Alex has both roles assigned, the token will bear both the requested scopes and the response will be similar to the following:

"scope":"news_read news_write", "token_type":"bearer", "expires_in":3299, 

This means that Chris can only access the GET operation of the API while Alex can access both having assigned to both the employee and manager roles.

Add Scopes

You can add scopes using a scope menu

Scope Name

A unique name for identifying the scope. Typically, it is prefixed by part of the API's name for uniqueness, but is not necessarily reader-friendly.


The description of the scope
The user role(s) that are allowed to obtain a token against this scope. e.g., manager, employee.


Note that the role name is case sensitive in the DBMSs that are case sensitive, such as PostgreSQL.

Applying a scope to an API

You can apply scopes to an API resource at the time the API is created or modified.

You can assign a global scope for an API as follows.

  1. Log in to the API Publisher and select an API.
  2. Click on resources in the navigation bar.
  3. Select the resource under Assign Global Scopes for API.

To apply scopes at resource level do the following

  1. Log in to the API Publisher and select an API.
  2. Click on resources from in the navigation bar.
  3. Select and expand a resource.
  4. Select the scope from the drop-down list and click Save.

  • Users can add multiple scopes for a resource.
  • Users can add a root level scopes for a resource and it will apply for the all the HTTP methods. Also, users can override the HTTP method level scopes.
  • Users can add multiple root level scopes for a resource and it will apply for the all the HTTP methods.
  • No labels