> ## 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 an application can access the Token Vault to get an access token to call third-party APIs.

# Call APIs with 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>

Token Vault organizes federated 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> 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 <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> 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](/docs/secure/tokens/token-vault/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](https://auth0.com/docs/api/authentication/login), the Auth0 SDK makes a `GET` request to the `/authorize` endpoint with the following additional parameters:

<table class="table">
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>connection</code></td>
      <td>The name of a social identity provider. In this case, <code>google-oauth2</code>.</td>
    </tr>

    <tr>
      <td><code>connection\_scope</code></td>
      <td>Requests additional scopes to be authorized for the connection. In this case, it includes the Google Calendar API scopes.<p /><p><strong>Note:</strong> 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 <a href="/docs/secure/tokens/token-vault/configure-token-vault#configure-federated-connection">Configure Token Vault</a>.</p></td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Requests Auth0 scopes to be authorized for the application. Include <code>offline\_access</code> to get an Auth0 refresh token from the Auth0 Authorization Server.</td>
    </tr>
  </tbody>
</table>

2. 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> 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 <Tooltip tip="Client ID: Identification value given to your registered resource from Auth0." cta="View Glossary" href="/docs/glossary?term=client+ID">client ID</Tooltip>, and application's credentials, such as <Tooltip tip="Client ID: Identification value given to your registered resource from Auth0." cta="View Glossary" href="/docs/glossary?term=client+secret">client secret</Tooltip> or Private Key <Tooltip tip="Client Secret: Secret used by a client (application) to authenticate with the Authorization Server; it should be known to only the client and the Authorization Server and must be sufficiently random to not be guessable." cta="View Glossary" href="/docs/glossary?term=JWT">JWT</Tooltip>.

5. The Auth0 Authorization Server verifies the request and responds with an Auth0 access token, refresh token, and <Tooltip tip="ID Token: Credential meant for the client itself, rather than for accessing a resource." cta="View Glossary" href="/docs/glossary?term=ID+token">ID token</Tooltip>. The application can use the ID token containing the user’s profile information to link user accounts. To learn more, read [User account linking](/docs/manage-users/user-accounts/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](#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:

<Tabs>
  <Tab title="Next.js">
    ```javascript lines
    // 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' });
    ```
  </Tab>

  <Tab title="HTTP">
    ```json lines
    POST https://YOUR_AUTH0_TENANT.auth0.com/oauth/token
    Request:
    {
      "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
      "client_id": "AUTH0_CLIENT_ID",
      "client_secret": "AUTH0_CLIENT_SECRET",
      "subject_token_type": "urn:ietf:params:oauth:token-type:refresh_token",
      "subject_token": "AUTH0_REFRESH_TOKEN",
      "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token"
      "connection": "google-oauth2",
      "login_hint": "idp_user_id"
    }
    ```
  </Tab>
</Tabs>

<table class="table">
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>The grant type. For Token Vault, set to <code>urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token</code></td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Client application ID</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Client secret. <strong>Note:</strong> You can use any client authentication method to get a federated access token.</td>
    </tr>

    <tr>
      <td><code>subject\_token\_type</code></td>
      <td>Type of subject token. For Token Vault, set to refresh token: <code>urn:ietf:params:oauth:token-type:refresh\_token</code></td>
    </tr>

    <tr>
      <td><code>subject\_token</code></td>
      <td>The Auth0 refresh token that the Auth0 Authorization Server validates to identify the user.</td>
    </tr>

    <tr>
      <td><code>requested\_token\_type</code></td>
      <td>The requested token type. For Token Vault, set to federated access token or <code>[http://auth0.com/oauth/token-type/federated-connection-access-token](http://auth0.com/oauth/token-type/federated-connection-access-token)</code></td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>The connection name, in this case, <code>google-oauth2</code>.</td>
    </tr>

    <tr>
      <td><code>login\_hint</code></td>
      <td>(Optional) The user ID for the identity provider. Only use <code>login\_hint</code> if the user has several accounts from the same connection. For instance, a user may connect their work and personal Google account.</td>
    </tr>
  </tbody>
</table>

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:

```json lines
{
   "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](#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](/docs/secure/tokens/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.