---
title: "Hosted OAuth - Token exchange"
method: POST
path: "/v3/connect/token"
tags: ["Authentication APIs"]
---

# Hosted OAuth - Token exchange

`POST /v3/connect/token`

The standard OAuth token endpoint for Hosted Authentication. This endpoint doesn't require authentication, as it is part of the auth process.
You can pass one of the following `grant_type` values:
- `authorization_code`: Exchange the `code` Nylas returns from the OAuth 2.0 authorization flow for tokens (`access_token` and `refresh_token`). - `refresh_token`: Use the existing `refresh_token` for an existing grant to issue a new `access_token`. You _must_ pass your API key in the `client_secret` field.
 - `client_credentials`: Issue a new short-lived (1 hour) `access_token` using an existing `grant_id`. You _must_ pass your API key in the `client_secret` field. This is mainly used in Scheduler implementations.

This endpoint accepts both `application/json` and `application/x-www-form-urlencoded` request body types. The body parameters are the same for both, with the same naming conventions.
For more information, see the [Hosted authentication with access token documentation](/docs/v3/auth/hosted-oauth-accesstoken/).
### Failed token exchange requests
Each OAuth `code` is a unique, one-time-use credential. If your token exchange fails, you must restart the OAuth process. If you try to pass the original `code` in another token exchange request, the provider rejects the `code` and Nylas returns an error.

## Request body

- union
  - object — Exchange an authorization code for access and refresh tokens.
    - `client_id` string, required — Your Nylas application's client ID.
    - `client_secret` string, required — Your Nylas application's API key.
    - `grant_type` 'authorization_code', required — Supports exchanging a `code` for a token, or refreshing an access token using a `refresh_token` and `client_credentials` for issuing short-lived access based on the grant id provided.
    - `code` string, required — The `code` from the OAuth 2.0 authorization flow.
    - `redirect_uri` string, url, required — The URL that Nylas uses to redirect the user to your project after they complete the authorization flow. This should match the `callback_uri` or `redirect_uri` that you used to get the `code` during your initial [authorization request](/docs/reference/api/authentication-apis/get_oauth2_flow/).
    - `code_verifier` string — The plaintext `code` verifier (`code_challenge`) that you created in your [authorization request](/docs/reference/api/authentication-apis/get_oauth2_flow/).
  - object — Use a refresh token to issue a new access token.
    - `client_id` string, required — Your Nylas application's client ID.
    - `client_secret` string, required — Your Nylas application's API key.
    - `grant_type` 'refresh_token', required — Supports exchanging a `code` for a token, or refreshing an access token using a `refresh_token` and `client_credentials` for issuing short-lived access based on the grant id provided.
    - `refresh_token` string, required — Required to refresh or request a short-lived access token.
  - object — Issue a short-lived access token for an existing grant.
    - `client_id` string, required — Your Nylas application's client ID.
    - `client_secret` string, required — Your Nylas application's API key.
    - `grant_type` 'client_credentials', required — Supports exchanging a `code` for a token, or refreshing an access token using a `refresh_token` and `client_credentials` for issuing short-lived access based on the grant id provided.
    - `grant_id` string, required — Required to request a short-lived access token for a specific grant.

## Response `200`

The token exchange was successful.

- object
  - `access_token` string — Supports exchanging a `code` for a token, or refreshing an access token using a `refresh_token`.
  - `expires_in` integer — The remaining lifetime of the access token, in seconds.
  - `id_token` string — A JSON web token (JWT) that contains identity information about a user. It's digitally signed by Nylas.
  - `email` string — The email address associated with the provider token exchange.
  - `refresh_token` string — Returned only if the `code` was requested using `access_type=offline`.
  - `scope` string — List of scopes associated with this token.
  - `token_type` string — Currently always `Bearer`.
  - `grant_id` string — The ID for the new grant.
  - `provider` 'google' | 'microsoft' | 'imap' | 'icloud' | 'yahoo' | 'ews' | 'zoom' — The provider name associated with the authorized grant. Only returned during the code exchange process.

## Other responses

- `400` — The token exchange was unsuccessful. Nylas returns a message with a description, and a link to troubleshooting documentation.

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)