Validate an Access Token
An Access Token is a credential that can be used by an application to access an API. Before you can validate an Access Token, you first need to know the format of the token. Auth0 issues Access Tokens in two formats: opaque and JSON Web Token (JWT).
Opaque Access Tokens
Opaque Access Tokens can be used with the
/userinfo endpoint to return a user's profile. If you receive an opaque Access Token, you don't need to validate it. You can use it with the
/userinfo endpoint, and Auth0 takes care of the rest.
To learn more about getting an opaque Access Token for the
userinfo endpoint, see Get an Access Token: Opaque Access Tokens.
JSON Web Token (JWT) Access Tokens
Access Tokens issued for the Auth0 Management API and Access Tokens issued for any custom API that you have registered with Auth0 will always be JSON Web Tokens (JWTs).
Auth0 Management API Access Tokens
An Access Token issued for the Auth0 Management API should be treated as opaque (regardless of whether it actually is), so you don't need to validate it. You can use it with the Auth0 Management API, and Auth0 takes care of the rest.
To learn more about getting an Access Token for the Auth0 Management API, see Auth0 Management API Tokens.
Custom API Access Tokens
To validate a JWT issued for a custom API that you have registered with Auth0, you will need to:
- Perform standard JWT validation
- Check additional standard claims
- Check permissions (scopes)
If any of these checks fail, the token is considered invalid, and the request must be rejected.
Perform standard JWT validation
Because the Access Token is a JWT, you will first need to perform the standard JWT validation steps. To learn about JWT validation, see Validate a JSON Web Token.
Check additional standard claims
If you've performed the standard JWT validation, you have already decoded the JWT's Payload and looked at its standard claims. Some additional claims to verify for Access Tokens include:
- Token audience (
aud, array of strings): Depending on the initial token request, the
audfield could contain both an audience corresponding to your custom API and an audience corresponding to the
userinfoendpoint. At least one of the audience values for the token must match the unique identifier of the target API as defined in your API's Settings in the Identifier field. To learn more about getting Access Tokens with multiple audiences, see Get an Access Token.
If this check fails, the token is considered invalid, and the request must be rejected.
The final step is to verify that the Application has been granted the permissions required to access your API. To do so, you will need to check an additional claim in the decoded JWT's Payload:
- Scopes (
scope, space-separated list of strings): Should match the permissions required for the endpoint being accessed.
For example, say your custom API provides three endpoints to read, create, or delete a user record:
/delete. When you registered your API with Auth0, you created three corresponding permissions:
create:usersprovides access to the
read:usersprovides access to the
delete:usersprovides access to the
In this case, if an Application requests to access the
/create endpoint, but the Access Token's
scope claim does not include the value
create:users, then the API should reject the request with
For an example using a simple timesheet API in Node.js, see Architecture Scenarios: Server Client + API - Node.js API Implementation, an implementation of a Client Credentials grant for a hypothetical scenario. To see the complete solution, visit Architecture Scenarios: Server Client + API.