API scopes allow you to define the API data accessible to your applications.
When you create an API in Auth0, you can use scopes to control how and what someone can access. For example, if you want users to be able to read and delete contact information, you would create the follow two scopes to reflect these two actions:
If you wanted to expand our example on asking for standard claims to include also the
read:contacts permission, then you would using something like the following sample URL to initiate the authentication flow using the Implicit grant:
https://YOUR_AUTH0_DOMAIN/authorize? audience=YOUR_API_AUDIENCE& scope=openid%20profile%20email%20read:contacts& response_type=id_token%20token& client_id=YOUR_CLIENT_ID& redirect_uri=https://YOUR_APP/callback& nonce=YOUR_CRYPTOGRAPHIC_NONCE state=YOUR_OPAQUE_VALUE
Note the differences between the example above and the example on asking for standard claims. In the example above, we want to get an Access Token, that will allow us to access the API, with the rights to do specific actions. To do so, we changed two parameters and added a new one:
audience: New parameter added for this example. Its value is the unique identifier of the API we want to get access to.
scope: We appended the value
read:contacts. This denotes the rights that we want to be granted at the API (in this case, read contact information).
response_type: We appended the value
token. This tells the Authorization Server (Auth0 in our case) to issue an Access Token as well, not only an ID Token. The Access Token will be sent to the API as credentials.
Define scopes using the Dashboard
You can define API scopes using the Dashboard. Select the API you want to edit, and open up its Scopes tab.
Provide the following parameters:
|Name||The name of your scope|
|Description||A friendly description for your scope|
Click Add when you've provided the requested values.
Limiting API scopes being issued
An application can request any scope and the user will be prompted to approve those scopes during the authorization flow. This may not be a desirable situation, as you may want to limit the scopes based on, for example, the permissions (or role) of a user.
This approach is discussed in more depth in some of our Architecture Scenarios. Specifically, you can review the entire Configure the Authorization Extension section of our SPA+API Architecture Scenario which demonstrates how to configure the Authorization Extension, and also create a custom Rule which will ensure scopes are granted based on the permissions of a user.