> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Token

> Exchange an Auth0 token for an external provider's access token stored in Token Vault, so your application can call external APIs on the user's behalf.

`POST /oauth/token`

Token Vault lets an application exchange an Auth0 token for an external provider's access token so it can call external APIs on the user's behalf. This exchange is built on OAuth 2.0 Token Exchange ([RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693)) and uses the `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token` grant type.

The grant supports two variants, which differ only by the `subject_token` you send:

* **Refresh token exchange**: Exchange an Auth0 refresh token for the external provider's access token. Use this when your application holds an Auth0 refresh token. To learn more, read [Refresh Token Exchange with Token Vault](/docs/secure/call-apis-on-users-behalf/token-vault/refresh-token-exchange-with-token-vault).
* **Access token exchange**: Exchange an Auth0 access token for the external provider's access token. Use this when a backend API receives only an Auth0 access token, such as from a Single-Page Application. To learn more, read [Access Token Exchange with Token Vault](/docs/secure/call-apis-on-users-behalf/token-vault/access-token-exchange-with-token-vault).

To learn more, read the [Token Vault documentation](/docs/secure/call-apis-on-users-behalf/token-vault).

## Remarks

* Before you can perform the exchange, you must [configure the connection for Token Vault](/docs/secure/call-apis-on-users-behalf/token-vault/configure-token-vault) and connect the user's external account through the [Connected Accounts flow](/docs/secure/call-apis-on-users-behalf/token-vault/connected-accounts-for-token-vault), which uses the [My Account API](/docs/manage-users/my-account-api).

* For the **refresh token exchange**, set `subject_token_type` to `urn:ietf:params:oauth:token-type:refresh_token`. Token Vault does not support refresh token rotation, so you must disable **Allow Refresh Token Rotation** for your application in the Auth0 Dashboard. You can use [DPoP](/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop) to bind Auth0-issued tokens to your client for additional security.

* For the **access token exchange**, set `subject_token_type` to `urn:ietf:params:oauth:token-type:access_token`. You must [create a Custom API Client](/docs/secure/call-apis-on-users-behalf/token-vault/configure-token-vault#create-custom-api-client) with the same identifier as your backend API and the Token Vault grant type enabled. The backend API authenticates itself with the Custom API Client's credentials.

* The scopes issued may differ from the scopes granted to the external account. In this case, a `scope` field is included in the response JSON.

* Auth0 returns a `401` status code if it can't find a user identity that matches the `connection` (and `login_hint`, when provided).

## Headers

<ParamField header="DPoP" type="string">
  A DPoP proof for the request. This is optional and only required if your application uses [Demonstrating Proof-of-Possession](/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop).
</ParamField>

<ParamField header="auth0-forwarded-for" type="string">
  End-user IP as a string value. Set this if you want [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling) protection to work in server-side scenarios.
</ParamField>

## Request Body

<ParamField body="grant_type" type="string" required>
  Denotes the flow you are using. For Token Vault, use `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token`.
</ParamField>

<ParamField body="subject_token_type" type="string" required>
  The type of the subject token. For the refresh token exchange, use `urn:ietf:params:oauth:token-type:refresh_token`. For the access token exchange, use `urn:ietf:params:oauth:token-type:access_token`.
</ParamField>

<ParamField body="subject_token" type="string" required>
  The Auth0 token that the Auth0 Authorization Server validates to identify the user. This is an Auth0 refresh token for the refresh token exchange, or an Auth0 access token for the access token exchange.
</ParamField>

<ParamField body="requested_token_type" type="string" required>
  Indicates what kind of token you want back. For Token Vault, use `http://auth0.com/oauth/token-type/federated-connection-access-token`.
</ParamField>

<ParamField body="connection" type="string" required>
  The name of the connection to the external provider, for example `google-oauth2`.
</ParamField>

<ParamField body="client_id" type="string" required>
  Your application's Client ID. For the access token exchange, this is the Custom API Client's Client ID. As for other grant types, you can also pass the Client ID in the Authorization header using HTTP Basic Auth.
</ParamField>

<ParamField body="client_secret" type="string">
  (Optional) Your application's Client Secret. You can use any client authentication method to get the external provider's access token. As for other grant types, you can also pass the Client Secret in the Authorization header using HTTP Basic Auth. Review alternatives in the [Auth0 Authentication API reference docs](https://auth0.com/docs/api/authentication#authentication-methods).
</ParamField>

<ParamField body="login_hint" type="string">
  (Optional) Only use `login_hint` if the user has several accounts from the same connection, such as a work Google account and a personal Google account. When you pass a value for `login_hint` during the token exchange, you explicitly identify which of the user's linked accounts the request is for.
</ParamField>

## Response

| Status | Description                                                                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200    | Successful response. Returns the external provider's access token with its scopes and expiry time.                                                          |
| 401    | Unauthorized. The subject token is invalid or expired, the client credentials are incorrect, or Auth0 can't find a user identity matching the `connection`. |
| 403    | Forbidden. The client does not have permission to perform the token exchange.                                                                               |

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "access_token": "<YOUR_GOOGLE_ACCESS_TOKEN>",
    "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid",
    "expires_in": 1377,
    "issued_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
    "token_type": "Bearer"
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="access_token" type="string">
  The external provider's access token. Use this token to call the external provider's API on the user's behalf.
</ResponseField>

<ResponseField name="scope" type="string">
  A space-delimited list of scopes granted for the external provider's access token.
</ResponseField>

<ResponseField name="expires_in" type="number">
  The lifetime of the access token in seconds.
</ResponseField>

<ResponseField name="issued_token_type" type="string">
  Confirms the format of the token returned.

  Value: `http://auth0.com/oauth/token-type/federated-connection-access-token`
</ResponseField>

<ResponseField name="token_type" type="string">
  Specifies the authentication scheme to use in the Authorization header. For Token Vault, this is `Bearer`.
</ResponseField>