openapi: 3.2.0 info: title: Nylas Authentication APIs API version: v3 summary: The complete Nylas v3 API — Email, Calendar, Contacts, Notetaker, Scheduling, Administration, and Migration. description: The Nylas API is designed using the REST ideology to provide simple and predictable URIs to access and modify objects. contact: url: https://www.nylas.com/ x-provenance: method: harvested first_party: true publisher: Nylas source: https://developer.nylas.com/_spec-files/nylas-api.yaml harvested: '2026-08-21' sha256: 7ff001d571e163b1ffe22178741b59f813d8208ec878157a839a33dc2c13fd35 bytes: 1666223 note: 'Published by Nylas as the unified contract for the Nylas v3 API and stored verbatim; API Evangelist added only this provenance block. Submitted by the provider in api-evangelist/nylas#1 and verified against the live URL before harvest: OpenAPI 3.1.0, 118 paths, 208 operations, 174 component schemas, 100% of operations carrying summary, description, tag and a unique operationId, x-code-samples on 208 of 208. This document REPLACES a 22-operation scaffold API Evangelist derived from reading the documentation, now quarantined under openapi/_scaffold/.' x-evidence: - url: https://developer.nylas.com/_spec-files/nylas-api.yaml what: the published unified contract, harvested verbatim 2026-08-21 (200, text/yaml, 1,666,223 bytes) - url: https://developer.nylas.com/.well-known/api-catalog what: RFC 9727 linkset advertising that URL as service-desc for api.us.nylas.com and api.eu.nylas.com (200, application/linkset+json) servers: - url: https://api.us.nylas.com description: U.S. - url: https://api.eu.nylas.com description: E.U. security: - ACCESS_TOKEN: [] - NYLAS_API_KEY: [] tags: - name: Authentication APIs description: 'Nylas provides two ways to handle authentication: - **Bring Your Own (BYO) Authentication**, which uses the `/v3/connect/custom` endpoint.' paths: /v3/connect/auth: get: operationId: get_oauth2_flow tags: - Authentication APIs summary: Hosted OAuth - Authorization Request description: 'The initial OAuth 2.0 authorization request. Use this endpoint with the required query parameters to start the OAuth 2.0 process. The query parameters pass details to the Nylas API about how the user should authenticate, and where they should go after authenticating. This endpoint supports the authorization code flow and optional PKCE settings for client-side only applications. For more information, see the Hosted OAuth with access token and Hosted OAuth with access token and PKCE documentation.' x-code-samples: - lang: bash label: cURL source: "curl --request GET \\\n --url 'https://api.us.nylas.com/v3/connect/auth?client_id=&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&provider=google&login_hint=user@example.com'\n" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\n// Build a hosted-authentication URL. Redirect the user to this URL to start\n// the OAuth flow; Nylas calls back to your `redirectUri` with an authorization\n// code that you exchange for a grant via `nylas.auth.exchangeCodeForToken()`.\nconst authUrl = nylas.auth.urlForOAuth2({\n clientId: \"\",\n provider: \"google\",\n redirectUri: \"http://localhost:3000/oauth/exchange\",\n loginHint: \"email_to_connect@example.com\",\n accessType: \"offline\",\n});\n\nconsole.log(authUrl);\n" - lang: python label: Python SDK source: "@app.route(\"/nylas/auth\", methods=[\"GET\"])\ndef login():\n if session.get(\"grant_id\") is None:\n config = URLForAuthenticationConfig({\"client_id\": \"\", \n \"redirect_uri\" : \"http://localhost:5000/oauth/exchange\"})\n\n url = nylas.auth.url_for_oauth2(config)\n return redirect(url)\n else:\n return f'{session[\"grant_id\"]}'\n\n@app.route(\"/oauth/exchange\", methods=[\"GET\"])\ndef authorized():\n if session.get(\"grant_id\") is None:\n code = request.args.get(\"code\")\n\n exchangeRequest = CodeExchangeRequest({\"redirect_uri\": \"http://localhost:5000/oauth/exchange\",\n \"code\": code, \"client_id\": \"\"})\n\n exchange = nylas.auth.exchange_code_for_token(exchangeRequest)\n session[\"grant_id\"] = exchange.grant_id\n\n return redirect(url_for(\"login\"))\n" - lang: ruby label: Ruby SDK source: "# frozen_string_literal: true\n\nrequire 'nylas'\nrequire 'sinatra'\n\nnylas = Nylas::Client.new(\n api_key: \"\"\n)\n\nset :show_exceptions, :after_handler\n\nerror 404 do\n 'No authorization code returned from Nylas'\nend\n\nerror 500 do\n 'Failed to exchange authorization code for token'\nend\n\n# Build the hosted-authentication URL and redirect the user there.\nget '/nylas/auth' do\n config = {\n client_id: \"\",\n provider: 'google',\n redirect_uri: 'http://localhost:4567/oauth/exchange',\n login_hint: '',\n access_type: 'offline'\n }\n\n url = nylas.auth.url_for_oauth2(config)\n redirect url\nend\n\n# Receive the authorization code and exchange it for a grant.\nget '/oauth/exchange' do\n code = params[:code]\n status 404 if code.nil?\n\n begin\n response = nylas.auth.exchange_code_for_token({\n client_id: \"\",\n redirect_uri: 'http://localhost:4567/oauth/exchange',\n code: code\n })\n rescue StandardError\n status 500\n else\n \"Grant_Id: #{response[:grant_id]} \\n Email: #{response[:email]}\"\n end\nend\n" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.AccessType;\nimport com.nylas.models.AuthProvider;\nimport com.nylas.models.UrlForAuthenticationConfig;\n\npublic class HostedAuthUrl {\n public static void main(String[] args) {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n\n // Build a hosted-authentication URL. Redirect the user to this URL to start\n // the OAuth flow; Nylas calls back to your `redirectUri` with an authorization\n // code that you exchange for a grant via `nylas.auth().exchangeCodeForToken()`.\n UrlForAuthenticationConfig config = new UrlForAuthenticationConfig.Builder(\n \"\",\n \"http://localhost:3000/oauth/exchange\")\n .provider(AuthProvider.GOOGLE)\n .accessType(AccessType.OFFLINE)\n .loginHint(\"email_to_connect@example.com\")\n .build();\n\n String url = nylas.auth().urlForOAuth2(config);\n\n System.out.println(url);\n }\n}\n" - lang: kotlin label: Kotlin SDK source: "import com.nylas.NylasClient\nimport com.nylas.models.AccessType\nimport com.nylas.models.AuthProvider\nimport com.nylas.models.UrlForAuthenticationConfig\n\nfun main() {\n val nylas = NylasClient.Builder(\"\").build()\n\n // Build a hosted-authentication URL. Redirect the user to this URL to start\n // the OAuth flow; Nylas calls back to your `redirectUri` with an authorization\n // code that you exchange for a grant via `nylas.auth().exchangeCodeForToken()`.\n val config = UrlForAuthenticationConfig.Builder(\n \"\",\n \"http://localhost:3000/oauth/exchange\")\n .provider(AuthProvider.GOOGLE)\n .accessType(AccessType.OFFLINE)\n .loginHint(\"email_to_connect@example.com\")\n .build()\n\n val url = nylas.auth().urlForOAuth2(config)\n\n println(url)\n}\n" parameters: - in: query name: client_id required: true description: Your Nylas application's client ID (or application ID). schema: type: string - in: query name: provider required: false description: 'The connector provider type that you set up with Nylas for this application. If the provider isn''t set, the user is directed to the Nylas Hosted login page and prompted to select their provider. Multiple providers can be set as a comma-separated list.' schema: type: string enum: - google - microsoft - imap - icloud - yahoo - ews - zoom - in: query name: redirect_uri required: true description: Your project's callback URI (used as the OAuth `redirect_uri`). This is where the OAuth provider sends a user after they authenticate using Hosted OAuth. This must be URL-encoded. schema: type: string example: redirect_uri=https%3A%2F%2Fapp.example.com& - in: query name: response_type required: true description: Specifies the type of response Nylas returns for the authorization flow. Should be set to `code` for the OAuth 2.0 flow, and `adminconsent` for the Microsoft admin consent service flow. schema: type: string enum: - code - adminconsent - in: query name: scope description: 'A space-delimited list of scopes that identify the resources that your application may access on the user''s behalf. If no scopes are set, Nylas uses the default connector scopes.' schema: type: string - in: query name: prompt required: false description: '(Optional) The prompt for the Hosted login page. This parameter can accept multiple values separated by a comma, without spaces in between. The order of the prompts affects the UI of the Hosted login page. If `provider` is not set, the user is redirected to the provider page directly, and the prompt is ignored.' schema: type: string default: select_provider enum: - select_provider - detect - select_provider,detect - detect,select_provider - in: query name: state description: (Optional) The state of the grant, returned after authentication. The maximum length is 256 characters. schema: type: string - in: query name: login_hint description: Prefill the login name (usually the email address) during the authentication flow. If a grant already exists for the provided email address, Nylas automatically re-authenticates the grant. schema: type: string - in: query name: access_type description: Specifies whether Nylas should return a refresh token along with the exchange token. This isn't suitable for client-side or JavaScript applications. schema: type: string enum: - offline - online - in: query name: code_challenge description: Specifies a Base64-encoded `code_verifier` without padding. The verifier is used as a server-side challenge during the authorization code exchange. schema: example: e96bf6686a3c3510e9e927db7069cb1cba9b99b022f49483a6ce3270809e68a2 type: string - in: query name: code_challenge_method description: Specifies the method used to encode the `code_verifier`. The verifier is used as a server-side challenge during the authorization code exchange. schema: example: S256 type: string enum: - plain - S256 default: plain - in: query name: credential_id description: 'The ID of an existing Nylas connector''s credential record. If you set the `response_type` value to `code` then you can use the credential to override an OAuth connector''s default settings and create a grant. You need to [create a credential record](/docs/reference/api/connector-credentials/create_credential/) before you can make a credential override request. If not provided, connector''s default "active_credential_id" is used. If you set the `response_type` value to `adminconsent`, with provider Microsoft, then this will be the OAuth of Microsoft''s Service Account Admin Consent flow. You need to [set up the Microsoft connector with an Admin Consent credential before you can make this request](/docs/v3/auth/bulk-auth-grants/#set-up-microsoft-admin-consent-flow).' schema: type: string example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47 - in: query name: options description: '(Google only) Set to `exclude_google_granted_scopes` to exclude Google-granted scopes from the authorization request.' schema: type: string example: options=exclude_google_granted_scopes responses: '302': description: Redirects user to provider's authorization page headers: Location: description: Location header. schema: type: string format: url example: 'https://accounts.google.com/o/oauth2/auth/oauthchooseaccount?prompt=consent&login_hint=email@google.com&access_type=offline&state= &redirect_uri=https://api.us.nylas.com/v3/connect/callback&response_type=code&client_id= ' '400': $ref: '#/components/responses/400' /v3/connect/token: post: operationId: exchange_oauth2_token tags: - Authentication APIs summary: Hosted OAuth - Token exchange description: '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.' security: [] requestBody: required: true description: '' content: application/json: schema: oneOf: - type: object title: Exchange code description: Exchange an authorization code for access and refresh tokens. required: - code - client_id - client_secret - redirect_uri - grant_type properties: client_id: example: type: string description: Your Nylas application's client ID. client_secret: example: type: string description: Your Nylas application's API key. grant_type: example: authorization_code type: string description: 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. enum: - authorization_code code: type: string description: The `code` from the OAuth 2.0 authorization flow. redirect_uri: example: https://example.com/callback-handler format: url type: string description: '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: example: nylas type: string description: 'The plaintext `code` verifier (`code_challenge`) that you created in your [authorization request](/docs/reference/api/authentication-apis/get_oauth2_flow/).' - type: object title: Refresh access token description: Use a refresh token to issue a new access token. required: - refresh_token - client_id - client_secret - grant_type properties: client_id: example: type: string description: Your Nylas application's client ID. client_secret: example: type: string description: Your Nylas application's API key. grant_type: example: refresh_token type: string description: 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. enum: - refresh_token refresh_token: example: type: string description: Required to refresh or request a short-lived access token. - type: object title: Client credentials description: Issue a short-lived access token for an existing grant. required: - grant_id - client_id - client_secret - grant_type properties: client_id: example: type: string description: Your Nylas application's client ID. client_secret: example: type: string description: Your Nylas application's API key. grant_type: example: refresh_token type: string description: 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. enum: - client_credentials grant_id: example: type: string description: Required to request a short-lived access token for a specific grant. responses: '200': description: The token exchange was successful. content: application/json: schema: type: object title: data properties: access_token: example: type: string description: Supports exchanging a `code` for a token, or refreshing an access token using a `refresh_token`. expires_in: example: 3600 type: integer default: 3600 description: The remaining lifetime of the access token, in seconds. id_token: example: type: string description: 'A JSON web token (JWT) that contains identity information about a user. It''s digitally signed by Nylas.' email: example: example@gmail.com type: string description: The email address associated with the provider token exchange. refresh_token: example: type: string description: Returned only if the `code` was requested using `access_type=offline`. scope: example: https://www.googleapis.com/auth/gmail.readonly profile type: string description: List of scopes associated with this token. token_type: example: Bearer type: string description: Currently always `Bearer`. grant_id: example: type: string description: The ID for the new grant. provider: example: google enum: - google - microsoft - imap - icloud - yahoo - ews - zoom type: string description: The provider name associated with the authorized grant. Only returned during the code exchange process. '400': description: The token exchange was unsuccessful. Nylas returns a message with a description, and a link to troubleshooting documentation. content: application/json: schema: type: object title: data properties: error: example: invalid_request type: string description: Error type constant. error_description: example: 'Missing required parameter: code' type: string description: A human-readable error description. error_uri: example: developer.nylas.com/docs/api/errors/400-response/ type: string description: A URL to the related documentation and troubleshooting regarding this error. error_code: example: 400 type: string description: Error code used for referencing the documentation, logs, and data stream. x-code-samples: - lang: bash label: cURL source: "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/token\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"client_id\": \"\",\n \"client_secret\": \"\",\n \"grant_type\": \"authorization_code\",\n \"code\": \"\",\n \"redirect_uri\": \"https://example.com/callback-handler\",\n \"code_verifier\": \"\"\n }'\n" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\n// Exchange the authorization code returned by Nylas for an access token and\n// grant ID. Call this from your OAuth callback handler with the `code` query\n// parameter that Nylas appends to your `redirectUri`.\nconst code = \"\";\n\ntry {\n const response = await nylas.auth.exchangeCodeForToken({\n clientId: \"\",\n redirectUri: \"http://localhost:3000/oauth/exchange\",\n code,\n // Only set `codeVerifier` if you used PKCE in the initial authorization request.\n // codeVerifier: \"\",\n });\n\n console.log(\"Grant ID:\", response.grantId);\n console.log(\"Access token:\", response.accessToken);\n} catch (error) {\n console.error(\"Error exchanging code for token:\", error);\n}\n" - lang: python label: Python SDK source: "from flask import Flask, request\nfrom nylas import Client\n\nnylas = Client(\n \"\",\n \"\",\n)\n\napp = Flask(__name__)\nREDIRECT_URI = \"http://localhost:9000/oauth/exchange\"\n\n@app.route(\"/oauth/exchange\", methods=[\"GET\"])\ndef exchange_code_for_token():\n code_exchange_response = nylas.auth.exchange_code_for_token(\n request={\n \"code\": request.args.get(\"code\"),\n \"client_id\": \"\",\n \"redirect_uri\": REDIRECT_URI,\n }\n )\n\n return {\n \"email_address\": code_exchange_response.email,\n \"grant_id\": code_exchange_response.grant_id,\n }\n" - lang: ruby label: Ruby SDK source: "# frozen_string_literal: true\n\nrequire 'nylas'\nrequire 'sinatra'\n\nnylas = Nylas::Client.new(\n api_key: \"\"\n)\n\nset :show_exceptions, :after_handler\n\n# Receive the authorization code from Nylas and exchange it for a grant.\nget '/oauth/exchange' do\n code = params[:code]\n status 404 if code.nil?\n\n begin\n response = nylas.auth.exchange_code_for_token({\n client_id: \"\",\n redirect_uri: 'http://localhost:4567/oauth/exchange',\n code: code\n })\n rescue StandardError\n status 500\n else\n grant_id = response[:grant_id]\n email = response[:email]\n\n \"Grant_Id: #{grant_id} \\n Email: #{email}\"\n end\nend\n" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.CodeExchangeRequest;\nimport com.nylas.models.CodeExchangeResponse;\n\npublic class ExchangeCodeForToken {\n public static void main(String[] args) {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n\n // Exchange the authorization code returned by Nylas for an access token and\n // grant ID. Call this from your OAuth callback handler with the `code` query\n // parameter that Nylas appends to your `redirectUri`.\n CodeExchangeRequest codeRequest = new CodeExchangeRequest.Builder(\n \"http://localhost:3000/oauth/exchange\",\n \"\",\n \"\")\n // Only set codeVerifier if you used PKCE in the initial authorization request.\n // .codeVerifier(\"\")\n .build();\n\n try {\n CodeExchangeResponse codeResponse = nylas.auth().exchangeCodeForToken(codeRequest);\n\n System.out.println(\"Grant ID: \" + codeResponse.getGrantId());\n System.out.println(\"Access token: \" + codeResponse.getAccessToken());\n } catch (Exception e) {\n System.err.println(\"Error exchanging code for token: \" + e);\n }\n }\n}\n" - lang: kotlin label: Kotlin SDK source: "import com.nylas.NylasClient\nimport com.nylas.models.CodeExchangeRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"\").build()\n\n // Exchange the authorization code returned by Nylas for an access token and\n // grant ID. Call this from your OAuth callback handler with the `code` query\n // parameter that Nylas appends to your `redirectUri`.\n val codeRequest = CodeExchangeRequest.Builder(\n \"http://localhost:3000/oauth/exchange\",\n \"\",\n \"\")\n // Only set codeVerifier if you used PKCE in the initial authorization request.\n // .codeVerifier(\"\")\n .build()\n\n try {\n val codeResponse = nylas.auth().exchangeCodeForToken(codeRequest)\n\n println(\"Grant ID: ${codeResponse.grantId}\")\n println(\"Access token: ${codeResponse.accessToken}\")\n } catch (e: Exception) {\n System.err.println(\"Error exchanging code for token: $e\")\n }\n}\n" /v3/connect/revoke: post: operationId: revoke_oauth2_token_and_grant tags: - Authentication APIs summary: Hosted OAuth - Revoke OAuth token description: 'Revokes the specified OAuth access token. When you revoke the token, Nylas _doesn''t_ revoke the grant or the associated provider token. This means that a user can re-authenticate to get a new access token for the existing grant, so their `grant_id` doesn''t change. If you revoke a Nylas access token, Nylas also revokes all child tokens and the parent `refresh_token` attached to the access token.' parameters: - in: query name: token schema: type: string required: true description: The token to revoke responses: '200': description: The token was revoked successfully. content: application/json: schema: type: object '400': description: The token could not be revoked, possibly because it was invalid or already expired. content: application/json: schema: type: object title: data properties: error: example: invalid_token type: string description: Error type constant. error_description: example: Token expired or revoked type: string description: Human readable error description. error_uri: example: developer.nylas.com/docs/api/errors/400-response/ type: string description: A url to the related documentation and troubleshooting regarding this error. error_code: example: 400 type: string description: Error code used for referencing the docs, logs and data stream. x-code-samples: - lang: bash label: cURL source: "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/connect/revoke?token=' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\n// Configure the Nylas SDK with your API key and server URL\nconst NylasConfig = {\n apiKey: \"\",\n apiUri: \"\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\nconst revokeToken = async () => {\n try {\n const token = \"\";\n const response = await nylas.auth.revoke(token);\n\n console.log(\"Token Revoked:\", response);\n } catch (error) {\n console.error(\"Error removing connector:\", error);\n }\n};\n\nrevokeToken();\n" - lang: python label: Python SDK source: "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\nrequest = nylas.auth.revoke(\n \"\",\n)\n\nprint(request)" - lang: ruby label: Ruby SDK source: "# frozen_string_literal: true\n\nrequire 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"\"\n)\n\nbegin\n nylas.auth.revoke(\"\")\n puts \"The token was successfully revoked\"\nrescue Nylas::NylasApiError => e\n puts \"The token could not be revoked: #{e.message}\"\nend\n" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.TokenParams;\n\npublic class Main {\n public static void main(String[] args) {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n TokenParams token = new TokenParams(\"\");\n\n try {\n boolean tokenStatus = nylas.auth().revoke(token);\n if (tokenStatus) {\n System.out.println(\"The token was successfully removed\");\n } else {\n System.out.println(\"The token cannot be removed\");\n }\n } catch (Exception e) {\n System.out.println(\"Invalid token cannot be removed\");\n }\n }\n}\n" - lang: kotlin label: Kotlin SDK source: "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main() {\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n val token = TokenParams(\"\")\n\n try {\n val tokenStatus = nylas.auth().revoke(token)\n if (tokenStatus) {\n println(\"The token was successfully removed\")\n } else {\n println(\"The token cannot be removed\")\n }\n } catch (e: Exception) {\n print(\"Invalid token cannot be removed\")\n }\n}\n" /v3/connect/tokeninfo: get: operationId: info_oauth2_token tags: - Authentication APIs summary: OAuth Token Info description: 'Get info about a specific token based on the identifier you include. Use _either_ the ID Token or Access Token. **Note**: Because Nylas uses the schema outlined in RFC 9068 to ensure that it is compatible with all OAuth libraries in all languages, the format for this endpoint is different from the other OAuth endpoints.' parameters: - in: query name: id_token schema: type: string description: ID token - in: query name: access_token schema: type: string description: Access token responses: '200': description: Returns Token info content: application/json: schema: type: object properties: request_id: type: string description: ID of the request example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 data: type: object properties: iss: type: string description: Token's issuer example: https://nylas.com aud: type: string description: Token's audience example: http://localhost:3030 sub: type: string description: Token's subject example: daf84d88-f274-46cc-bbc9-aed7dac061c7 email: type: string description: Email of grant's user token belongs to example: user@example.com iat: type: integer description: Token issued at example: 1692094848 exp: type: integer description: Token expires at example: 1692095173 '400': description: Bad request content: application/json: schema: type: object title: data properties: error: example: invalid_token type: string description: Error type constant. error_description: example: Token expired or revoked type: string description: Human readable error description. error_uri: example: developer.nylas.com/docs/api/errors/400-response/ type: string description: A url to the related documentation and troubleshooting regarding this error. error_code: example: 400 type: string description: Error code used for referencing the docs, logs and data stream. x-code-samples: - lang: bash label: cURL source: "curl --request GET \\\n --url 'https://api.us.nylas.com/v3/connect/tokeninfo?id_token=&access_token=' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\nconst accessToken = \"\";\n\ntry {\n const tokenInfo = await nylas.auth.accessTokenInfo(accessToken);\n console.log(\"Token info:\", tokenInfo);\n} catch (error) {\n console.error(\"Error fetching token info:\", error);\n}\n" - lang: python label: Python SDK source: "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\nrequest = nylas.auth.id_token_info(\n \"\",\n)\n\nprint(request)" - lang: ruby label: Ruby SDK source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(\n\t api_key: \"\"\n)\n\nquery_params = {\n id_token: \"\"\n}\n\ntoken_info = nylas.auth.access_token_info(query_params: query_params)\n\nputs token_info\n" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class GetTokenInfo {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n Response token = nylas.auth().idTokenInfo(\"\");\n \n System.out.println(token);\n }\n}\n" - lang: kotlin label: Kotlin SDK source: "import com.nylas.NylasClient\n\nfun main(args: Array) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n val token = nylas.auth().idTokenInfo(\"\")\n \n print(token)\n}\n" /v3/connect/custom: post: summary: Bring Your Own Authentication tags: - Authentication APIs operationId: byo_auth description: 'Manually creates a grant using the Bring Your Own (BYO) Authentication flow. If you''re handling the OAuth flow in your own project or you want to migrate existing users, BYO Auth lets you provide the user''s `refresh_token` to create a grant. If a user previously authenticated with your Nylas application using the same email address, Nylas detects this and re-authenticates their existing grant instead of creating a new one. The API response contains the user''s existing `grant_id`. ### Supported providers Pick the request body variant that matches your provider: - **Refresh token** — OAuth providers (`google`, `microsoft`, `yahoo`, `zoom`) using a standard refresh token. - **Credential override** — OAuth providers, but using a stored credential record to swap in different client credentials. - **Microsoft bulk auth** — Microsoft App Permissions. Requires a connector credential and the admin consent flow. - **Google bulk auth** — Google Service Accounts. Requires a connector credential and the Service Account flow. - **IMAP** — direct IMAP/SMTP credentials for any IMAP provider. - **iCloud** — an iCloud email address plus an Apple app password. - **EWS** — on-premises Microsoft Exchange; hosted Exchange should use Microsoft Graph instead. - **Virtual calendar** — a Virtual Calendar grant for scheduling without a third-party provider. - **Zoom Meetings** — Zoom OAuth. Your OAuth app must include the granular scopes `meeting:write:meeting`, `meeting:update:meeting`, and `meeting:delete:meeting`. - **Nylas (Agent Account)** — a fully Nylas-hosted Agent Account email and calendar mailbox on a domain you''ve registered with Nylas.' security: - NYLAS_API_KEY: [] requestBody: required: true description: '' content: application/json: schema: oneOf: - type: object title: Refresh token description: Use an OAuth refresh token to create a grant. required: - provider - settings properties: provider: type: string description: The user's OAuth provider. enum: - google - microsoft - yahoo - zoom settings: description: A list of settings required by the provider, including the `refresh_token`. example: refresh_token: 1//09XpDHQ6hq6PrCgYIARAAGAkSNwF... type: object properties: refresh_token: type: string description: The refresh token associated with the email account. example: 1//09XpDHQ6hq6PrCgYIARAAGAkSNwF... - type: object title: Credential override description: Override the connector's client credentials with a stored credential record. required: - provider - settings properties: provider: type: string description: The user's OAuth provider. enum: - google - microsoft - yahoo - zoom settings: description: 'A list of settings required by the provider, including the `refresh_token`. If you add the `credential_id` field with the UUID of an existing [credential record](/docs/reference/api/connector-credentials/), Nylas uses the provider''s `client_id` and `client_secret` from the credential record.' example: refresh_token: 1//09XpDHQ6hq6PrCgYIARAAGAkSNwF... credential_id: e280d2fa-86db-4937-81c9-ffbd539872d6 type: object properties: refresh_token: type: string description: The refresh token associated with the email account. example: 1//09XpDHQ6hq6PrCgYIARAAGAkSNwF... credential_id: type: string description: 'The UUID of an existing [credential record](/docs/reference/api/connector-credentials/) that Nylas can use to override the default connector settings.' - type: object title: Microsoft bulk auth description: Create a grant via Microsoft admin-consent App Permissions. required: - provider - settings properties: provider: type: string description: The user's OAuth provider. enum: - microsoft settings: description: 'A list of settings required by Microsoft. This sets the user''s email address and the Nylas `credential_id`. If a grant already exists for the provided email address, Nylas automatically starts the re-authentication process.' example: email_address: user@office365.com credential_id: e280d2fa-86db-4937-81c9-ffbd539872d6 type: object properties: email_address: type: string description: The user's email address. example: user@office365.com credential_id: type: string description: 'The ID of an existing `adminconsent` credential that Nylas can use to authenticate Microsoft App Permission grants.' example: e280d2fa-86db-4937-81c9-ffbd539872d6 - type: object title: Google bulk auth description: Create a grant via a Google Service Account. required: - provider - settings properties: provider: type: string description: The user's OAuth provider. enum: - google settings: description: 'A list of settings required by Google. This sets the user''s email address and the Nylas `credential_id`. If a grant already exists for the provided email address, Nylas automatically starts the re-authentication process.' example: email_address: user@gmailworkspace.com credential_id: e280d2fa-86db-4937-81c9-ffbd539872d6 type: object properties: email_address: type: string description: The user's email address. example: user@gmailworkspace.com credential_id: type: string description: 'The ID of an existing `serviceaccount` credential that Nylas can use to authenticate Google Service Account grants.' example: e280d2fa-86db-4937-81c9-ffbd539872d6 scopes: type: array items: type: string description: A list of scopes for the grant. example: - https://www.googleapis.com/auth/userinfo.email - https://www.googleapis.com/auth/userinfo.profile - https://www.googleapis.com/auth/gmail.readonly - type: object title: IMAP description: Create an IMAP grant using username, password, and server details. required: - provider - settings properties: provider: type: string description: The user's provider. enum: - imap settings: description: 'A list of settings needed for Nylas to connect to the provider''s IMAP server. If the provider uses a different address or credentials for SMTP (to send email), include that information separately in the SMTP fields.' example: imap_username: imap_password: imap_host: imap_port: '993' smtp_host: smtp_port: '465' smtp_username: smtp_password: type: object properties: imap_username: type: string description: The user's username or email address. example: nyla@example.com imap_password: type: string description: The user's email account password or app password. imap_host: type: string description: 'The IMAP host. If you don''t define the host in the request payload, Nylas tries to auto-detect the hostname using the provided `imap_username`. If you''re using a self-hosted IMAP server, you _must_ provide the hostname.' example: imap.mail.me.com imap_port: type: integer description: 'The IMAP port number. If you don''t define the port in the request payload, Nylas tries to auto-detect it using the provided `imap_username`. If you''re using a self-hosted IMAP server, you _must_ provide the port number.' example: 993 smtp_host: type: string description: 'The SMTP host. If you don''t define the host in the request payload, Nylas tries to auto-detect it using the provided `imap_username`. If you''re using a self- hosted SMTP server, you _must_ provide the hostname.' example: smtp.mail.me.com smtp_port: type: integer description: 'The SMTP port number. If you don''t define the port in the request payload, Nylas tries to auto-detect it using the provided `imap_username`. If you''re using a self-hosted SMTP server, you _must_ provide the port number.' example: 587 smtp_username: type: string description: 'The user''s SMTP username, if their SMTP credentials are different from their IMAP credentials.' example: nyla@example.com smtp_password: type: string description: 'The user''s SMTP password, if their SMTP credentials are different from their IMAP credentials.' - type: object title: iCloud description: Create an iCloud grant using an email address and app password. required: - provider - settings properties: provider: type: string description: The user's provider. enum: - icloud settings: description: A list of settings required by iCloud. example: username: password: type: object properties: username: type: string description: The user's iCloud email address. example: example@icloud.com password: type: string description: The user's app password. - type: object title: EWS description: Create a grant for an on-premises Microsoft Exchange account. required: - provider - settings properties: provider: type: string description: The user's provider. enum: - ews settings: description: A list of settings required by EWS. example: email: nyla@ews.example.com ews_username: ews_password: ews_host: type: object properties: email: type: string description: The user's email address. example: nyla@ews.example.com ews_username: type: string description: The user's Exchange username, formatted as an email address. example: nyla@ews.example.com ews_password: type: string description: The user's Microsoft Exchange password. ews_host: type: string description: 'The EWS host. If you don''t define the host in the request payload, Nylas tries to auto-detect it using the provided `ews_username`. If you''re using a self- hosted EWS server, you _must_ provide the hostname.' example: ews.mail.example.com ews_port: type: integer description: The EWS port number. default: 443 scope: type: array items: type: string description: A list of scopes for the grant. example: - ews.messages - ews.calendars - ews.contacts - type: object title: Virtual calendar description: Create a Virtual Calendar grant for scheduling without a provider. required: - provider - settings properties: provider: type: string description: The account's provider. enum: - virtual-calendar example: virtual-calendar settings: description: A list of settings required by Nylas. type: object properties: email: type: string description: 'The virtual account identifier. This can be any arbitrary string — it doesn''t have to be in email address format.' example: floor1desk24@example.com state: type: string description: 'An optional state value that Nylas returns to your project when the authentication flow completes. If you include the `state`, Nylas returns the unmodified value to your project. You can use this for verification, or to track information about the account. For more information about the `state` parameter, see the [OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749) or the [official OAuth 2.0 documentation](https://www.oauth.com/oauth2-servers/authorization/the-authorization-request/).' example: my-state - type: object title: Zoom Meetings description: Create a Zoom Meetings grant from an OAuth refresh token. required: - provider - settings properties: provider: type: string description: The user's OAuth provider (in this case, `zoom`). enum: - zoom settings: description: A list of settings required by Zoom. type: object properties: refresh_token: type: string description: The `refresh_token` from the Zoom `code` exchange flow. example: - type: object title: Nylas (Agent Account) description: Create a Nylas-hosted Agent Account on a domain you've registered. required: - provider - settings properties: provider: type: string description: The account's provider. Use `nylas` to create an Agent Account. enum: - nylas example: nylas name: type: string description: 'The Agent Account''s display name. Nylas stores this as the grant''s `name` and uses it as the default `From` display name when the account sends email, so a recipient sees `Sales Agent ` instead of the bare address. Omit it and the account sends with no display name. You can override the name on an individual message with the `from` field on [send](/docs/reference/api/messages/send-message/).' example: Sales Agent workspace_id: type: string description: 'The ID of the [workspace](/docs/reference/api/workspaces/) to place the Agent Account in. The workspace''s `policy_id` and `rule_ids` govern the account''s limits, spam detection, and mail rules. If omitted, Nylas auto-groups the account into a workspace whose `domain` matches the email address (when `auto_group` is enabled), or places it in the application''s default workspace.' example: abf6ff99-05ad-4c0a-aaf8-400aacf2470a settings: description: The settings required for a Nylas Agent Account. example: email: user@yourdomain.com type: object required: - email properties: email: type: string description: 'The Agent Account''s email address. The email''s domain must match a domain you''ve already [registered with Nylas](/docs/reference/api/manage-domains/).' example: user@yourdomain.com app_password: type: string description: 'Optional password that unlocks IMAP and SMTP-submission access to the Agent Account. Omit it and protocol-level access stays disabled. Must be 18–40 printable ASCII characters (codes 33–126) and contain at least one uppercase letter, one lowercase letter, and one digit. Stored as a bcrypt hash — it can''t be retrieved later, only reset by updating the grant. See [Connect mail clients to an Agent Account](/docs/v3/agent-accounts/mail-clients/).' minLength: 18 maxLength: 40 example: MySecureP4ssword!2024 x-code-samples: - lang: bash label: cURL (Microsoft) source: "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"microsoft\",\n \"settings\": {\n \"refresh_token\": \"\"\n }\n }'\n" - lang: bash label: cURL (Google) source: "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"google\",\n \"settings\": {\n \"refresh_token\": \"\"\n }\n }'\n" - lang: bash label: cURL (IMAP) source: "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"imap\",\n \"settings\": {\n \"imap_username\": \"user@example.com\",\n \"imap_password\": \"\",\n \"imap_host\": \"imap.example.com\",\n \"imap_port\": 993,\n \"smtp_host\": \"smtp.example.com\",\n \"smtp_port\": 587,\n \"smtp_username\": \"user@example.com\",\n \"smtp_password\": \"\"\n }\n }'\n" - lang: bash label: cURL (iCloud) source: "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"icloud\",\n \"settings\": {\n \"username\": \"user@icloud.com\",\n \"password\": \"\"\n }\n }'\n" - lang: bash label: cURL (Virtual Calendar) source: "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"virtual-calendar\",\n \"settings\": {\n \"email\": \"conference-room-3a@example.com\"\n }\n }'\n" - lang: bash label: cURL (Nylas Agent Account) source: "curl --location 'https://api.us.nylas.com/v3/connect/custom' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"nylas\",\n \"name\": \"Sales Agent\",\n \"workspace_id\": \"\",\n \"settings\": {\n \"email\": \"user@yourdomain.com\"\n }\n}'\n" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\n// Microsoft (refresh-token) Bring-Your-Own-Auth grant.\nasync function authenticateMicrosoft() {\n const grant = await nylas.auth.customAuthentication({\n requestBody: {\n provider: \"microsoft\",\n settings: {\n refreshToken: \"\",\n },\n scope: [\"Mail.Read\", \"Mail.Send\"],\n },\n });\n\n return grant;\n}\n\n// Nylas Agent Account grant — provisions a Nylas-hosted mailbox on a domain\n// you've registered with Nylas. No OAuth refresh token required.\nasync function authenticateAgentAccount() {\n const grant = await nylas.auth.customAuthentication({\n requestBody: {\n provider: \"nylas\",\n name: \"Sales Agent\",\n settings: {\n email: \"agent@yourdomain.com\",\n policyId: \"\",\n },\n },\n });\n\n return grant;\n}\n\nauthenticateMicrosoft()\n .then((grant) => console.log(\"Microsoft grant:\", grant))\n .catch((error) => console.error(\"Microsoft auth error:\", error));\n\nauthenticateAgentAccount()\n .then((grant) => console.log(\"Agent Account grant:\", grant))\n .catch((error) => console.error(\"Agent Account auth error:\", error));\n" - lang: ruby label: Ruby SDK source: "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"\",\n)\n\nrequest_body = {\n provider: '',\n settings: {'username': '', 'password': ''},\n scope: 'email.read_only,calendar.read_only,contacts.read_only',\n state: ''\n}\n\nauth = nylas.auth.custom_authentication(request_body)\nputs auth\n" - lang: python label: Python SDK source: "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\",\n)\n\nrequest_body = {\n \"provider\": \"icloud\",\n \"settings\": {\n \"username\": \"\",\n \"password\": \"\",\n },\n \"scope\": [\"email.read_only\", \"calendar.read_only\", \"contacts.read_only\"],\n \"state\": \"\",\n}\n\ngrant = nylas.auth.custom_authentication(request_body)\nprint(grant)\n" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\n\npublic class Main {\n public static void main(String[] args) throws\n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n\n AuthProvider provider = AuthProvider.ICLOUD;\n\n Map settings = new HashMap<>();\n settings.put(\"username\", \"\");\n settings.put(\"password\", \"\");\n\n List scopes = List.of(\n \"email.read_only\", \"calendar.read_only\", \"contacts.read_only\");\n\n CreateGrantRequest requestBody = new CreateGrantRequest.Builder(provider, settings)\n .state(\"\")\n .scopes(scopes)\n .build();\n\n Response grant = nylas.auth().customAuthentication(requestBody);\n System.out.println(grant);\n }\n}\n" - lang: kotlin label: Kotlin SDK source: "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main() {\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n val provider = AuthProvider.ICLOUD\n val settings = mapOf(\"username\" to \"\", \"password\" to \"\")\n val scopes = listOf(\"email.read_only\", \"calendar.read_only\", \"contacts.read_only\")\n\n val requestBody = CreateGrantRequest(provider, settings, \"\", scopes)\n val grant = nylas.auth().customAuthentication(requestBody)\n\n println(grant)\n}\n" responses: '201': content: application/json: schema: type: object properties: request_id: type: string description: The request ID. example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 data: $ref: '#/components/schemas/GrantObject' description: Grant Created '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/400' '401': description: Not Authenticated content: application/json: schema: $ref: '#/components/schemas/401' components: schemas: GrantObject: type: object required: - created_at - id - provider - scope properties: account_id: type: string description: 'The v2 Nylas account ID. This field appears only if the grant was created by migrating a v2 connected account.' example: df0yq6c9okc6t9j4ejd5nyrt7 blocked: type: boolean description: When `true`, indicates that the grant is blocked from accessing the Nylas APIs. example: false created_at: type: integer description: When the grant was created, in seconds using the Unix timestamp format. example: 1617817109 email: type: string description: 'The email address associated with the grant. If the provider supports `id_token` and exposes the user''s email address, Nylas automatically extracts this value.' example: nyla@example.com grant_status: type: string description: Specifies whether the grant is valid or the user needs to re-authenticate. enum: - invalid - valid example: valid id: type: string description: A unique identifier for the grant. example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47 ip: type: string description: 'The user''s client IP address. Mostly useful for [Hosted OAuth](/docs/v3/auth/hosted-oauth-apikey/).' example: 1.1.1.1 name: type: string description: The user's display name. example: Nyla provider: type: string description: The provider that the user authenticated with. enum: - ews - google - icloud - imap - microsoft - virtual-calendar - yahoo - zoom - nylas x-enum-descriptions: virtual-calendar: Nylas' [virtual calendars](/docs/v3/calendar/virtual-calendars/). nylas: Nylas [Agent Accounts](/docs/v3/agent-accounts/). example: microsoft provider_user_id: type: string description: The user's provider ID. This field might be changed at any time by the provider. example: b16f171c-6640-4edd-a598-e507b546d841 scope: type: array items: type: string description: 'An array of [granular scopes](/docs/dev-guide/scopes/) associated with the grant. If none are specified, Nylas uses the default scopes from the [connector](/docs/reference/api/connectors-integrations/).' example: - Mail.Read - User.Read - offline_access settings: type: object description: 'A list of settings associated with the grant. The contents of this object might differ between grants or depending on the provider.' email_aliases: type: array items: type: string description: "An array of found email aliases for this grant. Only returned if special query parameter `expose_aliases` for \n[Get Grant](/docs/reference/api/manage-grants/get_grant_by_id/) is used and set to `true`.\nApplicable only for Google and Microsoft grants.\nFor Microsoft, aliases require a Microsoft 365 / Exchange Online mailbox. Free Outlook.com\n(consumer) accounts have no aliases to expose, so this field is omitted from the response\neven when `expose_aliases=true`." example: - email_alias1@example.com - email_alias2@example.com state: type: string description: 'The initial state that was set as part of the authentication process. Nylas passes this value back to your project without modifying it. You can use this field for verification, or to track information about the user.' example: my-state updated_at: type: integer description: 'When the user last authenticated their grant, in seconds using the Unix timestamp format. Initially, this value is the same as `created_at`.' example: 1617817109 user_agent: type: string description: 'The user''s [client or browser information](https://www.useragents.me/). Mostly useful for [Hosted OAuth](/docs/v3/auth/hosted-oauth-apikey/).' workspace_id: type: string description: 'The ID of the Workspace the grant belongs to, if any. For grants from providers other than Agent Accounts, Nylas may omit this field when the grant is in the application''s default workspace.' example: abf6ff99-05ad-4c0a-aaf8-400aacf2470a credential_id: type: string description: The ID of the Credential the grant is associated with. Grant will use this Credential for provider communication. example: c123f8e1a-eb1c-41c0-b6a6-d2e59daf7f47 '401': type: object required: - request_id - error additionalProperties: false properties: request_id: description: ID of the request type: string example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 error: description: Error object type: object properties: type: type: string description: Type of error example: invalid_request_error message: description: Informative error message default: Authentication error type: string example: Authentication error provider_error: description: (OPTIONAL) informative error message from provider's side type: object example: error: invalid_grant provider_error: Bad Request '400': type: object required: - request_id - error additionalProperties: false properties: request_id: description: ID of the request type: string example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 error: description: Error object type: object properties: type: type: string description: Type of error example: bad_request message: description: Informative error message default: Bad request type: string example: Bad request provider_error: description: (OPTIONAL) informative error message from provider's side type: object example: error: invalid_grant provider_error: Bad Request responses: '400': description: Bad Request content: application/json: schema: title: error type: object properties: request_id: type: string description: The request ID. error: type: object description: The response error object. properties: type: type: string description: The error type. message: type: string description: The error message. provider_error: type: object description: The error from the provider. examples: Bad Request: value: request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88 error: type: invalid_request_error message: error parsing request body provider_error: code: TargetIdShouldNotBeMeOrWhitespace message: Id is malformed. Invalid Idempotency-Key: value: request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88 error: type: api.invalid_idempotency_key message: Idempotency-Key must be 256 characters or fewer. securitySchemes: ACCESS_TOKEN: scheme: bearer type: http bearerFormat: NYLAS_ACCESS_TOKEN description: 'The Nylas **access token** for a specific grant. Issued as part of OAuth 2.1 flow token exchange.' NYLAS_API_KEY: scheme: bearer type: http bearerFormat: NYLAS_API_KEY description: 'The Nylas **API key** provides application-level access to APIs and all grants. You can generate these from the Dashboard. Learn more about [authorizing requests](/docs/v3/auth/).' SCHEDULER_SESSION_TOKEN: scheme: bearer type: http bearerFormat: Session ID description: The Nylas Scheduler **session ID** that Scheduler UI Components use to authorize API requests.