Introduction to Scope Management with WSO2 API Manager

Why Scope Management is needed?

Today, the services are provided via APIs by many organizations. Therefore, these APIs need to be well secured. For an example, let us take an organization which has Finance, HR, Admin and Engineering Departments. All these entities call to a single API which includes all the required functionalities. But HR team should not have access to invoke Finance operations via the API, Engineering team should not be having access to invoke any other resources which belongs to HR, admin or Finance. In order to carry out this secure procedure, WSO2 Scope Management comes to the stage.

This concept is developed using OAuth2.0 scopes. The purpose of OAuth is authorize the access to a service through access token.

Example Scenario – User Management API

Let’s develop this scenario from the scratch.

1. Download the zip file and deploy the war file inside it via tomcat server.

 Downloading Tomcat and running it on mac – Open terminal and install tomcat              and run it with following commands. 

brew install tomcat

brew ls tomcat

/usr/local/Cellar/tomcat/8.5.16/bin/catalina run

Go to web browser and type localhost:8080 and you will be redirected to following screen. Select Manager App. Provide credentials and login. You can see the set of files listed. Click on /RESTService file. Note the url which is http://localhost:8080/RESTservice/ 

2. Download WSO2 API Manager from here and up the product. For more information please refer this article

3. Login to Publisher and create a new API called UserManagement API.

Name: UserManagementAPI

Context: /usermanagement/api/

Version: 1.0.0

API Definition: Methods should be added as below.

GET - rest/user/search/{user_id}

POST - rest/user/add

PUT - rest/user/update

DELETE - rest/user/delete/{user_id}


4. In the ‘Implement’ tab, give Production Endpoint and Sandbox Endpoint urls as http://localhost:8080/RESTservice/ and test it. Then Publish the API.

5. Login to Store as admin and click on Applications tab. Click on Add Application. Give it a name and create the application. Go to Production Keys tab. Click on ‘Generate Keys’ tab and generate the access token. This generated token is valid for one hour by default.

6. Then navigate to API tab and subscribe API by selecting the created application.

Testing resources

Go to API tab and click on API Console tab.

Testing the POST method

   "employeeId": 1, 
   "firstName": "John", 
   "lastName": "D", 
   "salary": 100000.0, 
   "status": "ACTIVE"

Let’s first create a user. Select POST method and send above payload. You should be getting a success message. As that you can test rest of the methods as well.

Creating Scopes

  1. Login to WSO2 carbon and create roles and users as below. When creating roles make sure to provide following permissions.

All Permissions -> Admin permission -> Configure -> Login

All Permissions -> Admin permission -> Manage -> API -> Subscribe

user 1 -> role 1

user 2 -> role 2

user 3 -> role 3

user 4 -> role 4

2. We are going to create 4 scopes for 4 resources and assign it it each role.

user 1 -> role 1 -> scope1_adduser

user 2 -> role 2 -> scope2_usersearch

user 3 -> role 3 -> scope3_userupdate

user 4 -> role 4 ->scope4_userremove

3. Go to Publisher and click on Edit API. Go to Manage API tab. Click on Add Scope. Provide details as below.

Scope Key - scope1_adduser

Scope Name - Add user

Roles - role15

4. Then for each method, add relevant scope as below.


5. Publish the API.

6. In the APIs tab navigate to API Console tab. Expand one method. There you can see that it is said that scope is required, which explains to invoke that method to the relevant user, the valid access token is required.


If you try to invoke method without signing in to the store, you will get following error message.


7. Now sign in to store with user1 credentials. Make sure you have made a new application and subscribed it to the created API. (If access token has been expired, regenerate it)

8. Try to invoke GET method. Even though you have signed in, still you cannot invoke the method. Therefore you need to request the access token through following cURL command.

curl -k -d "grant_type=password&username=<username>&password=<password>&scope=<scope>” -H "Authorization: Basic <Base64(Consumerkey:ConsumerSecret)>” -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

For this example,

curl -k -d "grant_type=password&username=user1&password=user1&scope=scope1_user_add" -H "Authorization: Basic VHhZZGVoWmF0QkRLN3pmZDgzSHlUY0FIek5RYTpBVDIyeDM3aDlacjBuU2pxUVN0aHZYUEc3U29h" -H "Content-Type: application/x-www-form-urlencoded"  https://localhost:8244/token

Getting Base64(Consumerkey:ConsumerSecret): This can be taken from Application tab -> Production tab -> show keys


Else you can place ConsumerKey: ConsumerSecret and take the base64 from here


If the user1 has valid access to requested scope, you will the get the valid access token with the response along with the scope.

You will get a response as:


So we requested for user1 his valid scope. Therefore we get the access token stating the correct scope name.

You can copy and paste the access token and invoke the specific method.


If you try to invoke another method with the same access token, you will get an error message. Because in this scenario, we have 4 different scopes for 4 methods.

I tried to invoke the DELETE method with the same access token, and I’m getting an error message.


If I want to get the access token for the delete method, we have to request it with correct user’s credentials.

DELETE method can only access by role4 which has been assigned to user4 through the scope scope4_removeuser’

There you have to login as user4 to the store, create a new application and subscribe the API and you may have to generate the keys as well. Then you have to request the access token as below and get the access token and paste it and invoke DELETE method.

curl -k -d "grant_type=password&username=user4&password=user4&scope=scope4_removeuser" -H "Authorization: Basic WV8zeENhQlkxakNhaXpwYjRTTlQ1NFdLemRzYTpYZXd6eUIwOGdsZjloTlhpeWVuSXdHT1c5ZElh" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8244/token




If you try to invoke a different access token for a different method from the same user credentials, then you will get a default access token which you cannot invoke methods.

Single access token for multiple scopes

Assume that one user has multiple roles.

user1 -> role1, role2, role3, role4

Login to carbon console and assign all four roles to user1.


Therefore user1 can request single access token for multiple scopes.

curl -k -d "grant_type=password&username=user1&password=user1&scope=scope1_user_add scope4_removeuser scope3_updateuser scop2_searchuser" -H "Authorization: Basic VHhZZGVoWmF0QkRLN3pmZDgzSHlUY0FIek5RYTpBVDIyeDM3aDlacjBuU2pxUVN0aHZYUEc3U29h" -H "Content-Type: application/x-www-form-urlencoded"

The response will be as follow.

{"access_token":"4c1350b0-20c2-36e9-9af9-2b9da517da5d","refresh_token":"2dfdab7d-f3e0-35ab-bd0a-2c0d181ff056","scope":"scop2_searchuser scope1_user_add scope3_updateuser scope4_removeuser","token_type":"Bearer","expires_in":3600}

With that access token, having logged in as user1, all the operations can be performed.



From this article we discussed about what is scoping is about. Why it is needed. Then we used a practical scenario from deploying a War file into tomcat server, creating an API from WSO2 API Manager, create resources testing resources. Then we came to creating scopes. Requesting token through cURL commands are explained in different examples including positive and negative scenarios. Finally it has been discussed how single access tokens can be used for multiple scopes when user is having multiple roles.


Read more "Introduction to Scope Management with WSO2 API Manager"