Skip to main content
Token Vault supports the access token exchange, which enables a client application to exchange an Auth0 access token (subject token) for an external provider’s access token (requested token). When a Single-Page Application (SPA) calls a backend API, it only passes an Auth0 access token in the Authorization header. Because the backend API does not receive any refresh tokens issued to the SPA, it cannot use the refresh token exchange to access the Token Vault to call external APIs. Instead, the backend API can exchange the Auth0 access token received from the SPA (subject token) for an external provider’s access token (requested token), otherwise known as the access token exchange. This process keeps the sensitive external credentials secure on the backend. In Auth0’s access token exchange, the backend API acts as both a client and a resource server:
  • Client: Uses its own credentials to securely perform the access token exchange with the Auth0 Authorization Server. In Auth0, you create a Custom API Client with the same identifier as the backend API. The backend API passes the Custom API Client’s credentials to securely perform the access token exchange with the Auth0 Authorization Server.
  • Resource server: Serves the backend API to the SPA and validates the Auth0 access token.
By acting as the intermediary between the SPA and Auth0 Authorization Server, the backend API prevents unauthorized clients from stealing the Auth0 token and using it to access the external provider on the user’s behalf.

​
Use cases

Common use cases for the access token exchange include:
  • A backend API: A user interacts with an SPA, which then calls a backend API to exchange an Auth0 access token for an external provider’s access token with the Auth0 Authorization Server.
  • Microservice architecture: Backend services, such as MCP servers or other OAuth 2.0 resource servers, that need to exchange access tokens to access external APIs.

​
How it works

The following sequence diagram describes end-to-end how to call external APIs using the access token exchange in Auth0:
Let’s walk through a real-world example: A user wants to schedule a meeting in their Google Calendar using an SPA.

​
Prerequisites

Before getting started, you must configure the access token exchange with Token Vault.

​
Step 1: Connect and authorize access

To schedule the meeting, the SPA needs to connect with Google via Auth0 and then receive the user’s permission to access the Google Calendar API. The user logs into the application via Google with the Connected Accounts flow, which uses the My Account API. After the My Account API validates and completes the Connected Accounts request, it stores the Google access and refresh tokens with the requested calendar scopes in the Token Vault.

​
Step 2: SPA calls backend API with Auth0 access token

When the SPA calls the backend API, it passes the Auth0 access token in the Authorization header to the backend API. The backend API validates the Auth0 access token by checking the following:
  • Signature: Verify the token’s signature using Auth0’s public key. This confirms that Auth0 issued the access token.
  • Issuer: Checks the iss claim in the token’s payload to confirm that the token was issued by your Auth0 tenant.
  • Audience: Checks the aud claim to ensure it matches the unique identifier of the backend API itself. This confirms that the token was specifically issued for this resource server.
  • Expiration: Validates the exp claim to ensure the token is still valid and has not expired.
  • Scopes: Checks the scope claim to determine what permissions the user has been granted.
After successfully completing these checks, the backend API can trust the Auth0 access token and proceed with the token exchange.

​
Step 3: Backend API performs access token exchange

For the access token exchange, you need to create a Custom API Client linked to the backend API. The Custom API Client has the same identifier as your backend API and has the Token Vault grant type enabled. When the backend API performs the access token exchange, it authenticates itself by passing the Custom API Client’s credentials to the Auth0 Authorization Server, proving that it is the same entity that was registered in the Auth0 Dashboard. To perform the access token exchange, the backend API calls Auth0 SDKs to make a POST request to the /oauth/token endpoint. In the token request, the backend API:
  • Passes the backend API’s (the Custom API Client’s) client credentials to the Auth0 Authorization Server to authenticate itself.
  • Exchange an Auth0 access token for a Google access token.
curl --request POST 'https://{yourDomain}/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CUSTOM_API_CLIENT_ID",
    "client_secret": "YOUR_CUSTOM_API_CLIENT_SECRET",
    "subject_token": "YOUR_AUTH0_ACCESS_TOKEN",
    "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
    "connection": "google-oauth2"
  }'
ParameterDescription
grant_typeThe grant type. For Token Vault, set to urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_idClient application ID
client_secretClient secret. Note: You can use any client authentication method to get an external provider’s access token.
subject_token_typeType of subject token. For the access token exchange, set to the access token: urn:ietf:params:oauth:token-type:access_token.
subject_tokenThe Auth0 access token that the Auth0 Authorization Server validates to identify the user.
requested_token_typeThe requested token type. For Token Vault, set to the external provider’s access token or http://auth0.com/oauth/token-type/federated-connection-access-token
connectionThe connection name, in this case, google-oauth2.
login_hint(Optional) Only use login_hint if the user has several accounts from the same connection, such as a work Google account and personal Google account. When you pass in a value for the login_hint during the token exchange, you are explicitly identifying which of the user’s multiple linked accounts the request is for.

​
Step 4: Auth0 Authorization Server validates access token

The Auth0 Authorization Server validates and loads the user profile associated with the Auth0 access token:
  • Auth0 verifies that the client making the access token exchange request is linked to the backend API identified by the audience of the access token.
  • Auth0 checks if the user profile’s connected_accounts array contains a user account with the connection name passed in the authorization request.
  • If the authorization request contains login_hint, Auth0 looks for an identity matching both the connection name and the login_hint.
  • If Auth0 can’t find the user, it returns a 401 status code with an error message.
Once the Auth0 Authorization Server validates the user, it locates the Google access token within the Token Vault. If it is still valid, Auth0 returns the Google access token with its scopes and expiry time: 
{
  "access_token": "<YOUR_GOOGLE_ACCESS_TOKEN>",
  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.addons.execute https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.events.readonly https://www.googleapis.com/auth/calendar.settings.readonly https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid",
  "expires_in": 1377,
  "issued_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "token_type": "Bearer"
}
Using the Google access token, the backend API calls the Google Calendar API on the user’s behalf to schedule the meeting.