Advanced Configurations

This section explains how to configure scope to role mappings for API Manager REST APIs.

Changing Default Roles

Certain resources of the REST API are protected using OAuth 2.0 scopes. Each tenant has a tenant-conf.json configuration file with a section for RESTAPIScopes that contain a mapping between all the scopes that are available with API Manager REST APIs, and a set of roles.

When a user requires access to a resource protected by an OAuth 2.0 scope, an access token associated with that particular scope needs to be provided as the Bearer token in the Authorization header. In order to retrieve the token, the user has to invoke the Token API and request for that scope. For more information, see the Authorization section in REST API documents. When issuing such an access token, the Token API validates the eligibility of the user for that particular scope using the RESTAPIScopes configuration. An access token with the particular scope is issued for the user only if that user has been assigned one or more of the roles specified in the RESTAPIScopes configuration for that scope.

You can modify the default roles defined in RESTAPIScopes configuration according to your requirements via the Admin Portal UI. For more information, refer Managing Permissions.


Restart the server for the RESTAPIScopes configuration changes to take effect.

Configuring Allowed Origins

By default, each of the Product REST APIs (except Admin REST APIs) allows requests from all origins. If only a specific set of origins should be allowed to access a Product REST API, the allowed origins for that particular REST API should be configured as a system parameter. The defined system parameters are as follows.

  • For Publisher REST APIs :
  • For Developer Portal REST APIs :
  • For Gateway REST APIs :

The allowed origins for a particular REST API can be configured as a system parameter as follows.


  • The origin will have the following syntax.
<scheme>://<hostname>[ :<port> ]

Method 1- Specify the allowed origins in the deployment.toml file under [system.parameter]

  1. Open the <API-M_HOME>/repository/deployment.toml file and specify the allowed origins for the REST APIs under [system.parameter].

    '' = "<comma-separated-origins>"
    '' = "<comma-separated-origins>"
    '' = "<comma-separated-origins>"
    '' = ""
    '' = ","
    '' = ","
  2. Start the server to apply the changes.

    • On Linux/Mac OS: ./
    • On Windows: api-manager.bat

Method 2- Specify the allowed origins when starting the server

This can be done in one of two ways.

Option 1: Specifying the allowed origins in the server startup script

  1. Specify the allowed origins for the REST APIs in the server startup script stored in the <PRODUCT_HOME>/bin directory. ( for Linux/Mac OS and api-manager.bat for Windows)<comma-separated-origins> \<comma-separated-origins> \<comma-separated-origins> \, \,
  2. Start the server.

    • On Linux/Mac OS: ./
    • On Windows: api-manager.bat

Option 2: Specify the allowed origins during server startup

Start the API-M server by specifying the allowed origins for the REST APIs as system parameters.

  • Linux/Mac OS
./ \<comma-separated-origins> \<comma-separated-origins> \<comma-separated-origins>
./ \ \, \,
  • Windows
api-manager.bat \<comma-separated-origins> \<comma-separated-origins> \<comma-separated-origins>
api-manager.bat \ \, \,