Call APIs with Token Vault

Token Vault is currently available in Early Access for public cloud tenants. To enable Token Vault, contact your Auth0 representative.

Token Vault organizes federated access and refresh tokens issued by external providers into tokensets, with one tokenset per authorized connection. Applications can access the Token Vault when they exchange a valid Auth0 refresh token for a federated access token stored in the tokenset. This enables applications to request federated access tokens without the user having to re-authorize the connection. Using the federated access token, the application can call third-party APIs on the user’s behalf.

Let’s walk through a real-world example: A user wants to schedule a meeting in their Google Calendar using a productivity app.

Prerequisites

Before getting started, you must configure Token Vault.

Get access to third-party API

To schedule the meeting, the productivity app needs the user’s permission to access the Google Calendar API.

When the user logs into a new Google social connection:

1. Similar to a regular social login flow, the Auth0 SDK makes a GET request to the /authorize endpoint with the following additional parameters:

Parameter	Description
connection	The name of a social identity provider. In this case, google-oauth2.
connection_scope	Requests additional scopes to be authorized for the connection. In this case, it includes the Google Calendar API scopes. Note: At runtime, the list of connection scopes is merged with the scopes you statically configured for the connection. Whenever the user is redirected to authorize this connection, Auth0 will always request the scopes you selected. To learn more, read Configure Token Vault.
scope	Requests Auth0 scopes to be authorized for the application. Include offline_access to get an Auth0 refresh token from the Auth0 Authorization Server.

2. The Auth0 Authorization Server redirects the user to the consent prompt for the Google connection. The user authenticates using one of the configured login options and authorizes the Google connection, giving the application permission to access the Google Calendar API.

3. The Auth0 Authorization Server redirects the user back to the application with the single-use authorization code.

4. The Auth0 SDK makes a POST request to the /oauth/token endpoint with the authorization code, application’s client ID, and application’s credentials, such as client secret or Private Key JWT.

5. The Auth0 Authorization Server verifies the request and responds with an Auth0 access token, refresh token, and ID token. The application can use the ID token containing the user’s profile information to link user accounts. To learn more, read User account linking.

6. The Auth0 Authorization Server stores the Google access and refresh tokens in a secure tokenset within the user’s Token Vault.

Call third-party API

To schedule the meeting, the application needs to call the Google Calendar API. The application can use a valid Auth0 refresh token to request a Google access token with the scopes granted in the login flow without the user having to re-authorize the connection. To learn more, read Manage federated refresh tokens.

To call the Google Calendar API:

1. The application calls Auth0 SDKs to make a request to the /oauth/token endpoint with the following parameters:

Next.js

// Install the Auth0 Next.js SDK
npm i @auth0/nextjs-auth0

// Get access token for Google social connection
const { token } = await auth0.getAccessTokenForConnection({ connection: 'google-oauth2' });

Parameter	Description
grant_type	The grant type. For Token Vault, set to urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_id	Client application ID
client_secret	Client secret. Note: You can use any client authentication method to get a federated access token.
subject_token_type	Type of subject token. For Token Vault, set to refresh token: urn:ietf:params:oauth:token-type:refresh_token
subject_token	The Auth0 refresh token that the Auth0 Authorization Server validates to identify the user.
requested_token_type	The requested token type. For Token Vault, set to federated access token or http://auth0.com/oauth/token-type/federated-connection-access-token
connection	The connection name, in this case, google-oauth2.
login_hint	(Optional) The user ID for the identity provider. Only use login_hint if the user has several accounts from the same connection. For instance, a user may connect their work and personal Google account.

The Auth0 Authorization Server validates and loads the user profile associated with the Auth0 refresh token:

1. Auth0 checks if the user profile’s identities array contains a user account with the connection name passed in the authorization request.
2. If the authorization request contains login_hint, Auth0 looks for an identity matching both the connection name and the login_hint.
3. 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 federated access token within the Token Vault. If it is still valid, Auth0 returns the federated access token with its scopes and expiry time:

{
   "access_token": "GOOGLE_ACCESS_TOKEN",
   "scope": "https://www.googleapis.com/auth/calendar       https://www.googleapis.com/auth/calendar.events"
   "expires_in": 3600,
   "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
   "token_type": "Bearer"
}

If the federated access token has expired, Auth0 uses the federated refresh token stored in the Token Vault to get a new federated access token with the same scopes. Auth0 then stores it in the corresponding tokenset and returns it to the application. To learn more about how Auth0 manages federated refresh tokens, read Manage federated refresh tokens.

Using the federated access token, the application calls the Google Calendar API on the user’s behalf.

Manage federated refresh tokens

Auth0 securely stores the federated refresh and access tokens of external providers in a tokenset within the Token Vault, with one tokenset per authorized connection. Auth0 manages federated refresh tokens on the server, so your application only has to handle storing and exchanging Auth0 refresh tokens for federated access tokens.

To learn more about how Auth0 manages Auth0 refresh tokens for different types of applications, read Refresh tokens.

Federated refresh token expiration policy

Auth0 deletes federated refresh tokens from tokensets when they expire based on the expiration date set by the external provider or if they have not been exchanged for a federated access token for 1+ years.