> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-quickstart-revamp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn how to configure Token Vault.

# Configure Token Vault

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Token Vault is currently available in Early Access for public cloud tenants. To enable Token Vault, contact your Auth0 representative.
</Callout>

Auth0 supports Token Vault for the following social and enterprise <Tooltip tip="Identity Provider (IdP): Service that stores and manages digital identities." cta="View Glossary" href="/docs/glossary?term=identity+providers">identity providers</Tooltip>:

* Google
* Microsoft
* Box
* Slack
* GitHub
* <Tooltip tip="OpenID: Open standard for authentication that allows applications to verify users' identities without collecting and storing login information." cta="View Glossary" href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect
* Custom social connection

Once a user authenticates with a supported external provider and authorizes the federated connection, you can get an <Tooltip tip="Access Token: Authorization credential, in the form of an opaque string or JWT, used to access an API." cta="View Glossary" href="/docs/glossary?term=access+token">access token</Tooltip> to call third-party APIs on the user’s behalf. To learn more, read [Call APIs with Token Vault](/docs/secure/tokens/token-vault/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.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  If you have previously set your MFA policy to **Always** in the Auth0 Dashboard, you need to set it to **Never** to retrieve an access token from Token Vault. Otherwise, you will receive an error. To learn more about the different MFA policies, read [Enable MFA in the Auth0 Dashboard](/docs/secure/multi-factor-authentication/enable-mfa#enable-mfa-in-the-auth0-dashboard).

  If you need to trigger MFA challenges for interactive flows, enable **Customize MFA Factors using Actions** when [setting up MFA for your tenant](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login#prepare-your-tenant). You can then use an Action to trigger an MFA challenge based on the `event.transaction.protocol` property. To learn more, read [Customize MFA selection for Universal Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login).
</Callout>

## Configure application

Configure your application with the Token Exchange (Federated Connection) grant type using the <Tooltip tip="Management API: A product to allow customers to perform administrative tasks." cta="View Glossary" href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Management+API">Management API</Tooltip>.

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`.

<Tabs>
  <Tab title="Auth0 Dashboard">
    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**.

    <Frame>
      <img src="https://mintcdn.com/docs-staging-quickstart-revamp/A1o6LcInzX_m5Dvq/images/cdy7uua7fh8z/4pDrKjLpUISfhhGAfc0EaU/28517676a42ec418c75a7034a0cad343/configure_federated_connection_token_exchange.png?fit=max&auto=format&n=A1o6LcInzX_m5Dvq&q=85&s=84f734384423dd89648fb115da287151" alt="" width="1854" height="840" data-path="images/cdy7uua7fh8z/4pDrKjLpUISfhhGAfc0EaU/28517676a42ec418c75a7034a0cad343/configure_federated_connection_token_exchange.png" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    To enable Token Vault for an application, make a `PATCH` call to the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to add the `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token` grant type to the client JSON object:

    ```bash lines
    curl --location --request PATCH 'https://{tenantDomain}/api/v2/clients/{clientId}' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer {your_management_api_access_token}' \
      --data '{
        "grant_types": [
          "authorization_code",
          "refresh_token",
          "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token"
        ]
      }'
    ```
  </Tab>
</Tabs>

## Configure federated connection

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 <Tooltip tip="Refresh Token: Token used to obtain a renewed Access Token without forcing users to log in again." cta="View Glossary" href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> 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](#manage-tokensets).

<Tabs>
  <Tab title="Auth0 Dashboard">
    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**.

    <Frame>
      <img src="https://mintcdn.com/docs-staging-quickstart-revamp/rHYM5iMy6d7A-FVR/images/cdy7uua7fh8z/69jDhgpWbFY1npKDNY9wOT/360db4a0140ff3a3a68f169f3b99c98c/Screenshot_2025-04-03_at_07.49.56.png?fit=max&auto=format&n=rHYM5iMy6d7A-FVR&q=85&s=d966db0999c8a98560af202c9dbcf6c8" alt="" width="975" height="392" data-path="images/cdy7uua7fh8z/69jDhgpWbFY1npKDNY9wOT/360db4a0140ff3a3a68f169f3b99c98c/Screenshot_2025-04-03_at_07.49.56.png" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    To enable Token Vault for a supported social and enterprise connection, make a `PATCH` call to the [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint and set `federated_connections_access_tokens` to `true` in the `options` object:

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      When you use the `options` parameter when making a `PATCH` call to the [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint, you override the existing `options` object with the `options` object in your request body. As a result, make sure you include your entire `options` object in your request body.
    </Callout>

    ```bash lines
    curl --location --request PATCH 'https://{tenantDomain}/api/v2/connections/{connectionId}' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer {your_management_api_access_token}' \
      --header 'Accept: application/json' \
      --data '{
        "options": {
          "federated_connections_access_tokens": {
            "active": true
          },
          ...
        }
      }'
    ```
  </Tab>
</Tabs>

## Manage tokensets

The Auth0 <Tooltip tip="Authorization Server: Centralized server that contributes to defining the boundaries of a user’s access. For example, your authorization server can control the data, tasks, and features available to a user." cta="View Glossary" href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> 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](#get-user-s-tokensets)
* [Delete a tokenset](#delete-a-tokenset)

### Get user’s tokensets

To get a user's tokensets, you need a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the `read:federated_connections_tokensets` scope.

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

```bash lines
curl --request GET \
  --url 'https://{tenantDomain}/api/v2/users/{user_id}/federated-connections-tokensets' \
  --header 'Authorization: Bearer {your_management_api_access_token}'
```

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

```json lines
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.

### Delete a tokenset

To delete a tokenset, you need a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the `update:federated_connections_tokensets` scope.

Make a `DELETE` request to the `/tokensets` endpoint:

```bash lines
curl --request DELETE \
  --url 'https://{tenantDomain}/api/v2/users/{user_id}/federated-connections-tokensets/{tokenset_id}' \
  --header 'Authorization: Bearer {your_management_api_access_token}'
```

If successful, you should receive the following response:

```json lines
Response: 204 No-Content
```