OAuth 2.0 scopes

OAuth scopes specify the extent of an access token’s usefulness by providing a way to limit its access level. A scope defines what an access token can do, and what resources it can access.For example, an access token issued to a client app may be granted read and write access to protected resources, or just read. Scopes are often listed on a consent page (if shown to the resource owner), and there are no standardized scopes.

In API Gateway, you can define scopes, provide descriptions of scopes for end-users, and assign scopes to resources and individual methods within your API.

Before providing an access token to a client app, the Authorization Server displays a consent page to a resource owner and prompt the resource owner to grant the client app appropriate scopes. This way, resource owners can choose whether to allow the client app access to their data, which is a requirement for the client app to function properly.

When an edge server receives a client app request for a protected resource, API Gateway checks that the scopes in the request match the scopes configured for the HTTP method and resource combination (for example, GET http://bookstore.api.com/users) included in the request. If the access token that a client app sends in the request to the origin server does not contain the scopes associated with the HTTP method and resource combination, API Gateway rejects the request submitted by the client app with a 403 HTTP error code response.

In API Definitions, you can associate HTTP methods (such as GET or POST) with each API resource that you define. Methods inherit scopes from their top-level resource, and you can also assign scopes to methods individually. The inherited scopes do not override a method’s own scopes and conversely, a method’s scopes do not affect the inheritance. Each scope a method inherits from a resource is added to the method’s individual scopes.

For example, if you assign an ALL scope to a resource named order, then assign a READ scope to the order’s GET method, the GET method has the following scopes: ALL, READ. Another method of the same resource, for example PUT, only has the ALL scope inherited from the order resource.

OAuth scopes example

Scope names

You can name a scope whatever you like, but it’s recommended to use fully qualified uniform resource identifiers (URIs) for scope names, for example: http://bookstore.api.com/users/id.read. This ensures that each scope has a unique name and prevents granting access to resources inadvertently.

Scopes may contain characters from the hex character range x21 (!) to x7E (~) with the exception of x22 (") and x5C (\).