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
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. 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. 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. For more details on the signing algorithms go to the 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 clients 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 your Machine to Machine Applications. You can authorize which Machine to Machine Applications can request Access Tokens for your API. You can optionally select a subset of the defined scopes to further limit the access that an authorized client has. Only Machine to Machine Applications require explicit permission. That is because, when you authorize a non-interactive Client to access an API, Auth0 is creating a Client Grant for that Client. For more details on this case refer to: Setting up a Client Credentials Grant using the Management Dashboard.
Test: from this view you can execute a sample Client Credentials flow with any of your Authorized Machine to Machine 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
Allow Skipping User Consent: When a first party client 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 Client's callbackURL is
127.0.0.1the consent dialog will always be displayed.
Allow Offline Access: If this setting is enabled, Auth0 will allow clients 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. For more details on the signing algorithms see the Signing Algorithms paragraph below.
When you create an API you have to select the algorithm your tokens will be signed with. The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.
To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that. That algorithm, which is part of the JWT header, is the one you select for your API:
RS256 is an asymmetric algorithm which means that there are two keys: one public and one private (secret). Auth0 has the secret key, which is used to generate the signature, and the consumer of the JWT has the public key, which is used to validate the signature.
HS256 is a symmetric algorithm which means that there is only one secret key, shared between the two parties. The same key is used both to generate the signature and to validate it. Special care should be taken in order for the key to remain confidential.
The most secure practice, and our recommendation, is to use RS256. Some of the reasons are:
With RS256 you are sure that only the holder of the private key (Auth0) can sign tokens, while anyone can check if the token is valid using the public key.
Under HS256, if the secret key is compromised (e.g. by the client) you would have to re-deploy the API with the new secret.
With RS256 you can request a token that is valid for multiple audiences.
With RS256 you can implement key rotation without having to re-deploy the API with the new secret.
Verify an RS256 signed token
Go to Dashboard > Applications. Open the Settings of your client, scroll down and open Advanced Settings. Open the Certificates tab and you will find the Public Key in the Signing Certificate field.
If you want to use the Public Key to verify a JWT signature on JWT.io, you can copy the Public Key and paste it in the Public Key or Certificate field under the Verify Signature section on the JWT.io website.
If you want to verify the signature of a token from one of your applications, we recommend that you get the Public Key from your tenant's JSON Web Key Set (JWKS). Your tenant's JWKS is
For a more detailed overview of the JWT signing algorithms refer to: JSON Web Token (JWT) Signing Algorithms Overview.