Configure Token Vault

Once a user authenticates with a supported external provider and authorizes the connection, your application can access Token Vault to exchange an Auth0 token for an external provider’s access token.

To configure Token Vault, you need to:

1. Enable Token Vault for a supported social or enterprise connection.

2. Configure your application with the Token Vault grant type. 

3. Configure the token exchange for your application:

   • Refresh token exchange

   • Access token exchange

4. Manage tokensets within the Token Vault for your connection. 

Use the Auth0 Dashboard or Management API to configure a supported social or enterprise connection to retrieve and store access tokens for external APIs in the Token Vault.

Once you enable Token Vault for your connection, access and refresh tokens will no longer be stored in the user’s identities array. Instead, they will be stored in a secure tokenset within the Token Vault. To learn more, read Manage tokensets.

Auth0 DashboardManagement API

To enable Token Vault for a supported social and enterprise/custom connection:

1. Navigate to Authentication > Social Connections or Enterprise Connections.

2. Select Create Connection or select an existing connection.

3. In Permissions, select the desired scopes for your connection. You can filter by scope name or keywords. Whenever the user is redirected to authorize this connection, Auth0 always requests the scopes you selected. At runtime, this list is automatically completed with any additional scopes included in the connection_scope parameter of the authorization request.

4. In Advanced, toggle Enable Token Vault.

5. Select Save Changes.

Configure your application with the Token Vault grant type using the Auth0 Dashboard or Management API.

Only certain types of clients can use the Token Vault grant type:

1. The client must be a first-party client, i.e. the is_first_party property is true.

2. The client must be a confidential client with a valid authentication mechanism, i.e. the token_endpoint_auth_method property must not be set to none.

3. The client must be OIDC conformant, i.e. the oidc_conformant must be true.

Auth0 DashboardManagement API

1. Navigate to Applications > Applications. 

2. Select the application you want to configure. 

3. Under Advanced Settings > Grant Types, select the Token Vault grant type.

4. Select Save Changes.

For each user's authorized connection, like Google or Microsoft, Token Vault creates a secure container called a tokenset. A tokenset contains the access and refresh tokens needed to call that external provider's APIs on the user's behalf.

To manage tokensets for a user, use the Management API:

• Get user's tokensets

• Delete a tokenset

To get a user's tokensets, you need a Management API access token with the read:federated_connections_tokensets scope.

Make a GET request to the /federated-connections-tokensets endpoint:

curl --request GET \
  --url 'https://{yourDomain}/api/v2/users/{userId}/federated-connections-tokensets' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>'

If successful, you should receive a list of tokensets for the user: 

Status Code: 200
[{
  "connection": "google-oauth2",
  "id": "some-unique-tokenset-id1",
  "issued_at": 1733455897,
  "expires_at": 1733455897,
  "last_used_at": 1733453897,
  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events",
},{
  "id": "some-unique-tokenset-id2",
  "connection": "google-oauth2",
  "issued_at": 1733455897,
  "expires_at": 1733455897,
  "last_used_at": 1733453897,
  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events",
},{
  "connection": "google-oauth2",
  "issued_at": 1733455897,
  "id": "some-unique-tokenset-id3",
  "expires_at": 1733455897,
 "last_used_at": 1733453897,
  "scope": "Calendar.Read Calendar.Write",
}]

Note: The value for last_used_at is updated max once per day. 

To delete a tokenset, you need a Management API access token with the update:federated_connections_tokensets scope.

Make a DELETE request to the /tokensets endpoint:

curl --request DELETE \
  --url 'https://{yourDomain}/api/v2/users/{userId}/federated-connections-tokensets/{tokensetId}' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>'

If successful, you should receive the following response: 

Response: 204 No-Content

When you delete a tokenset, Auth0 removes the external provider’s access and refresh tokens from the Token Vault. This does not revoke the external provider’s tokens, and the refresh token could still be used to obtain new access tokens. You have to manually revoke the tokens for the external provider if they have been shared or copied elsewhere.