An API is an entity that represents an external resource, capable of accepting and responding to protected resource requests made by applications. At the OAuth2 spec an API maps to the Resource Server.
When an application wants to access an API's protected resources it must provide an Access Token. The same Access Token can be used to access the API's resources without having to authenticate again, until it expires.
Each API has a set of defined permissions. Applications can request a subset of those defined permissions when they execute the authorization flow, and include them in the Access Token as part of the scope request parameter.
For example, an API that holds a user's appointments, may accept two different levels of authorization: read only (scope
read:appointments) or write (scope
write:appointments). When an application asks the API to list a user's appointments, then the Access Token should contain the
read:appointments scope. In order to edit an existing appointment or create a new one, the Access Token should contain the
write:appointments scope. See Tokens for more information.
How to configure an API in Auth0
Click on the APIs menu option on the left.
Click the + Create API button.
You need to provide the following information for your API:
Name: a friendly name for the API. Does not affect any functionality.
Identifier: a unique identifier for the API. Auth0 recommends using a URL. Auth0 does differentiate between URLs that include the last forward slash. For example, https://example.com and https://example.com/ are two different identifiers. The URL does not have to be a publicly available URL. Auth0 will not call your API. This value cannot be modified afterwards.
Signing Algorithm: the algorithm to sign the tokens with. The available values are
RS256. When selecting
RS256the token will be signed with the tenant's private key. To learn more about signing algorithms, see Signing Algorithms paragraph.
Fill in the required information and click the Create button.
Once you do so you will be navigated to the Quick Start of your API. Here you can find details on the implementation changes you have to do to your API, which basically consists of choosing a JWT library from a predefined list and configuring this library to validate the Access Tokens in your API.
The other available views for your API are:
Settings: lists the settings for your API. Some are editable. Here you can change the token expiration time and enable offline access (this way Auth0 will allow your applications to ask for Refresh Tokens for this API). For details refer to the API Settings paragraph.
Scopes: here you can define the scopes for this API, by setting a name and a description.
Machine to Machine Applications: lists all applications for which the Client Credentials grant is enabled. By default, this grant is enabled for Regular Web Applications and Machine to Machine Applications. You can authorize any of these applications to request Access Tokens for your API. Optionally, you can select a subset of the defined scopes to limit your authorized application's access.
Test: from this view, you can execute a sample Client Credentials flow with any of your authorized applications to check that everything is working as expected.
Click on the Settings tab of your API to review the available settings:
Id: A unique alphanumeric string generated by Auth0. The information is read only and you will only need it if you will be working directly with Auth0's Management API Resource Servers endpoints.
Name: A friendly name for the API. Does not affect any functionality. The following characters are not allowed:
Identifier: A unique identifier for your API. This value is set upon API creation and cannot be modified afterwards. We recommend using a URL but note that this doesn't have to be a publicly available URL, Auth0 will not call your API at all.
Token Expiration (Seconds): The amount of time (in seconds) before the Auth0 Access Token expires. The default value is 86400 seconds (24 hours). The maximum value you can set is 2592000 seconds (30 days).
Allow Skipping User Consent: When a first party application requests authorized access against an API with the Allow Skipping User Consent flag set, the User Consent dialog will not be shown to the final user. Note that if the hostname of your application's callback URL is
127.0.0.1the consent dialog will always be displayed.
Allow Offline Access: If this setting is enabled, Auth0 will allow applications to ask for Refresh Tokens for this API.
Signing Algorithm: The algorithm to sign the tokens with. The available values are
RS256. When selecting
RS256(recommended) the token will be signed with the tenant's private key. This value is set upon API creation and cannot be modified afterwards. To learn more about signing algorithms, see Signing Algorithms.