Sign in
Authentication APIs

Hosted OAuth - Token exchange

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.

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.

post/v3/connect/token

Request body

OR
OR

Example request

{
  "client_id": "<NYLAS_CLIENT_ID>",
  "client_secret": "<NYLAS_API_KEY>",
  "grant_type": "authorization_code",
  "redirect_uri": "https://example.com/callback-handler",
  "code_verifier": "nylas"
}

Response

The token exchange was successful.

access_tokenstring

Supports exchanging a code for a token, or refreshing an access token using a refresh_token.

expires_ininteger

The remaining lifetime of the access token, in seconds.

id_tokenstring

A JSON web token (JWT) that contains identity information about a user. It's digitally signed by Nylas.

emailstring

The email address associated with the provider token exchange.

refresh_tokenstring

Returned only if the code was requested using access_type=offline.

scopestring

List of scopes associated with this token.

token_typestring

Currently always Bearer.

grant_idstring

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.

Example response

{
  "access_token": "<NYLAS_ACCESS_TOKEN>",
  "expires_in": 3600,
  "id_token": "<JWT_TOKEN>",
  "email": "example@gmail.com",
  "refresh_token": "<REFRESH_TOKEN>",
  "scope": "https://www.googleapis.com/auth/gmail.readonly profile",
  "token_type": "Bearer",
  "grant_id": "<NYLAS_GRANT_ID>",
  "provider": "google"
}

Changes