Configure Token Vault

Auth0 supports Token Vault for the following social and enterprise identity providers:

• Google

• Microsoft

• Box

• Slack

• GitHub

• OpenID Connect

• Custom connection

Once a user authenticates with a supported external provider and authorizes the federated connection, you can get an access token to call third-party APIs on the user’s behalf. To learn more, read Call APIs with Token Vault.

To configure Token Vault, you need to:

1. Configure your application with the Token Exchange (Federated Connection) grant type. 

2. Enable Token Vault for a federated connection.

3. Manage tokensets within the Token Vault for your federated connection. 

Configure your application with the Token Exchange (Federated Connection) grant type using the Auth0 Dashboard or Management API.

Only certain types of clients can use the Token Exchange (Federated Connection) 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 Exchange (Federated Connection) grant type.

4. Select Save Changes.

Use the Auth0 Dashboard or Management API to configure a federated connection to retrieve and store access tokens for third-party 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.

The Auth0 Authorization Server securely stores the user's access and refresh token in the Token Vault, which maintains one tokenset per authorized connection.

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:

GET https://example.us.auth0.com/api/v2/users/{user_id}/federated-connections-tokensets
Authorization: Bearer <M2M_TOKEN_FOR_API_V2_WITH_READ:federated_connections_tokensets>

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:

DELETE https://example.auth0.com/api/v2/users/{user-id}/federated-connections-tokensets/{tokenset-id}
Authorization: Bearer <M2M_TOKEN_FOR_API_V2_WITH_UPDATE:federated_connections_tokensets>

If successful, you should receive the following response: 

Response: 204 No-Content