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

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

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 OAuth2 bearer token can not grant access to any API resource beyond its associated scopes.

If you generate a new access token after either modifying or deleting a scope of an API resource that you had previously invoked, you will not be able to access that particular resource of the API for a period of 15 minutes, which is the default Gateway cache period, because the WSO2 API Manager Gateway is designed to cache the details of the resource on its side. However, you will be able to immediately invoke other resources that correspond to that particular API. For a detailed description and a sample real-world scenario on scope management with OAuth scopes, see An Overview of Scope Management with WSO2 API Manager, which is a WSO2 library article.

In addition to defining a scope via the publisher as explained in the article mentioned above, the WSO2 API Manager also allows defining a scope and attach it to a resource via Swagger. The following sections explain how to do with sample swagger definitions.

Defining a scope via swagger
  1. The swagger definition of the API needs to be changed in order  to achieve this. x-wso2-scopes"  key will define a scope for the API. It  should be nested underx-wso2-security".  Note that the role should be an already available role in the system. To define a role see Adding and Managing Users and Roles. Find the sample Swagger definition below for reference.
  "x-wso2-security": {
            "apim": {
              "x-wso2-scopes": [{
                "name": "scope1",
                "description": "scope 1",
                "key": "scope1",
                "roles": "role1"

Attaching the scope to a resource
  1. The swagger defintion of the API needs to be changed inoreder to achieve this. Define thex-scope" key under the resource to attach a scope to a resource. The value to this key should be the scope name. Note that the scope should be an already defined. Find the sample Swagger definition below for reference.
   "paths": {"/CheckPhoneNumber":
           {"get": {
            "x-auth-type": "Application",
            "x-throttling-tier": "Unlimited",
			"x-scope": "scope1",
            "responses": {"200": {"description": "OK"}}

Once you have done the changes to the swagger definition of the API as above , you can use this swagger to create the API as described in Create and Publish API from a Swagger Defininton.

  • No labels