Hosted OAuth - Token exchange - Authentication Apis - API Reference

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.

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

client_id*string

Your Nylas application's client ID.

Example: "<NYLAS_CLIENT_ID>"

client_secret*string

Your Nylas application's API key.

Example: "<NYLAS_API_KEY>"

grant_type*string

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.

authorization_code

Example: "authorization_code"

code*string

The code from the OAuth 2.0 authorization flow.

redirect_uri*string<url>

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.

Example: "https://example.com/callback-handler"

code_verifierstring

The plaintext code verifier (code_challenge) that you created in your authorization request.

Example: "nylas"

Responses

access_tokenstring

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

Example: "<NYLAS_ACCESS_TOKEN>"

expires_ininteger

The remaining lifetime of the access token, in seconds.

Default: 3600

Example: 3600

id_tokenstring

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

Example: "<JWT_TOKEN>"

emailstring

The email address associated with the provider token exchange.

Example: "[email protected]"

refresh_tokenstring

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

Example: "<REFRESH_TOKEN>"

scopestring

List of scopes associated with this token.

Example: "https://www.googleapis.com/auth/gmail.readonly profile"

token_typestring

Currently always Bearer.

Example: "Bearer"

grant_idstring

The ID for the new grant.

Example: "<NYLAS_GRANT_ID>"

providerstring

The provider name associated with the authorized grant. Only returned during the code exchange process.

googlemicrosoftimapicloudyahooewszoom

Example: "google"

curl --request POST \ --url "https://api.us.nylas.com/v3/connect/token" \ --header 'Content-Type: application/json' \ --data '{ "client_id": "<NYLAS_CLIENT_ID>", "client_secret": "<NYLAS_API_KEY>", "grant_type": "authorization_code", "code": "<AUTHORIZATION_CODE>", "redirect_uri": "https://example.com/callback-handler", "code_verifier": "<CODE_VERIFIER>" }'