openapi: 3.2.0 info: title: Nylas Manage Grants 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: Manage Grants description: Grants are the main objects that power Nylas, because they _grant_ your Nylas application specific scopes of access (for example, permission to read email messages) to the user's resources and data on their provider. paths: /v3/connect/custom: post: summary: Bring Your Own Authentication tags: - Manage Grants 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' /v3/grants: get: summary: Return all grants tags: - Manage Grants operationId: get-all-grants description: Returns all grants in your Nylas application. security: - NYLAS_API_KEY: [] parameters: - name: account_id in: query schema: type: string description: 'Returns grants with a matching v2 Nylas account ID. Only applicable for grants migrated from Nylas v2.' - name: account_ids in: query schema: type: string description: 'Returns grants with a matching list of v2 Nylas account IDs. Only applicable for grants migrated from Nylas v2.' - name: before in: query schema: type: integer description: 'Returns grants whose `created_at` value is less than or equal to the defined value, in seconds using the Unix timestamp format.' - name: email in: query schema: type: string example: nyla@example.com description: Returns grants with a matching `email`. - name: grant_status in: query schema: type: string enum: - invalid - valid description: Filters for only valid or invalid grants. - name: ip in: query schema: type: string description: Returns grants with a matching IP address. - name: limit in: query schema: type: integer default: 10 description: 'The maximum number of grants to return. See [Pagination](/docs/reference/api/#pagination) for more information.' - name: offset in: query schema: type: integer default: 0 description: 'The offset value for the request. See [Pagination](/docs/reference/api/#pagination) for more information.' - name: order_by in: query schema: type: string enum: - asc - desc default: desc description: The order in which Nylas should sort results for the request. - name: provider in: query schema: type: string description: Returns grants with a matching `provider`. - name: since in: query schema: type: integer description: 'Returns grants whose `created_at` value is greater than or equal to the defined value, in seconds using the Unix timestamp format.' - name: sort_by in: query schema: type: string enum: - created_at - updated_at default: created_at description: The field Nylas should use to sort results for the request. - name: workspace_id in: query schema: type: string description: Returns grants in the specified workspace. x-code-samples: - lang: bash label: cURL source: 'curl --request GET \ --url ''https://api.us.nylas.com/v3/grants?limit=3&provider=google'' \ --header ''Accept: application/json'' \ --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\nasync function listGrants() {\n try {\n const grants = await nylas.grants.list();\n\n console.log(\"Grants found:\", grants);\n } catch (error) {\n console.error(\"Error finding grants:\", error);\n }\n}\n\nlistGrants();\n" - lang: python label: Python SDK source: "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\",\n)\n\ngrants = nylas.grants.list()\n\nprint(grants)\n" - lang: ruby label: Ruby SDK source: "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: ''\n)\n\ngrants, _ = nylas.grants.list()\n\ngrants.each do |grant|\n puts \"#{grant}\\n\\n\"\nend\n" - lang: java label: Java SDK source: "// Import Nylas packages\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.List;\n\npublic class read_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n ListResponse grants = nylas.grants().list();\n\n for(Grant grant : grants.getData()){\n System.out.println(grant);\n }\n }\n}" - lang: kotlin label: Kotlin SDK source: "// Import Nylas packages\nimport com.nylas.NylasClient\n\nfun main(args: Array) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n val grants = nylas.grants().list().data;\n \n for(grant in grants){\n println(grant)\n }\n}\n" responses: '200': description: Success. Returns an array of Grant objects. content: application/json: schema: type: object properties: request_id: type: string description: The request ID. example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 data: type: array items: $ref: '#/components/schemas/GrantObject' limit: type: integer example: 10 offset: type: integer example: 0 '401': description: 'Error: Not authenticated' content: application/json: schema: $ref: '#/components/schemas/401' '404': description: 'Error: not found' content: application/json: schema: $ref: '#/components/schemas/404' /v3/grants/{grantId}: get: parameters: - name: grantId schema: example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 type: string in: path required: true - name: expose_aliases schema: type: boolean default: false in: query required: false description: 'If set to `true`, the response will include an array of email aliases associated with the grant. Applicable only for Google and Microsoft grants. Not set by default. For Microsoft, aliases are only available for Microsoft 365 / Exchange Online mailboxes. Free Outlook.com (consumer) accounts have no aliases to expose, so the `email_aliases` field is omitted from the response entirely. Email aliases are only returned for the called API, not stored in the grant object permanently.' operationId: get_grant_by_id tags: - Manage Grants summary: Get a grant description: 'Gets a grant with the provided ID. If the grant''s `grant_status` is `invalid`, the grant has expired and needs to be re-authenticated. See Handling expired grants for best practices on detection and recovery.' x-code-samples: - lang: bash label: cURL source: "curl --request GET \\\n --url 'https://api.us.nylas.com/v3/grants/' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\n// Instantiate Nylas SDK\nconst NylasConfig = {\n apiKey: \"\",\n apiUri: \"\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\n// Define the ID of the grant to find\nconst grantId = \"\";\n\n// Function to find the grant\nasync function findGrant() {\n try {\n const grant = await nylas.grants.find({ grantId });\n\n console.log(\"Grant found:\", grant);\n } catch (error) {\n console.error(\"Error finding grant:\", error);\n }\n}\n\nfindGrant();\n" - lang: python label: Python SDK source: "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\n\ngrant = nylas.grants.find(\n grant_id\n)\n\nprint(grant)" - lang: ruby label: Ruby SDK source: "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: ''\n)\n\ngrant, _ = nylas.grants.find(grant_id: \"\")\n\nputs grant" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class get_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n Response grant = nylas.grants().find(\"\");\n \n System.out.println(grant);\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 grant = nylas.grants().find(\"\")\n print(grant)\n}\n" security: - NYLAS_API_KEY: [] responses: '200': content: application/json: schema: type: object properties: request_id: type: string description: ID of the request example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 data: $ref: '#/components/schemas/GrantObject' description: Returns Grant object '401': description: Not Authenticated content: application/json: schema: $ref: '#/components/schemas/401' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/404' patch: parameters: - name: grantId schema: example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 type: string in: path required: true operationId: patch_grant_by_id tags: - Manage Grants summary: Update a grant description: 'Updates the specified grant''s stored settings or scope metadata. **Common use cases:** - **Rotate a refresh token** — If you obtain a new `refresh_token` from a provider (for example, after a user re-consents in your own OAuth flow), you can update the grant''s stored token without deleting and recreating the grant. Pass the new token in `settings.refresh_token`. - **Update stored scope list** — Update the `scope` array to reflect the scopes the grant currently holds. Note: this only updates the scope metadata stored by Nylas. It does **not** change the actual permissions the provider has granted. To change provider permissions, the user must re-authenticate through the provider''s OAuth consent flow. When you make a `PATCH` request, Nylas replaces all data in the nested object with the information included in your request. For more information, see Updating objects.' x-code-samples: - lang: bash label: cURL source: "curl --request PATCH \\\n --url 'https://api.us.nylas.com/v3/grants/' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --data '{\n \"settings\": {\n \"refresh_token\": \"\"\n },\n \"scope\": [\"Mail.Read\", \"Mail.Send\", \"User.Read\", \"offline_access\"]\n }'\n" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst NylasConfig = {\n apiKey: \"\",\n apiUri: \"\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\nasync function updateGrant() {\n try {\n const grant = await nylas.grants.update({\n grantId: \"\",\n requestBody: {\n scope: [\"mail.ready\"],\n },\n });\n\n console.log(\"Updated Grant:\", grant);\n } catch (error) {\n console.error(\"Error to update grant:\", error);\n }\n}\n\nupdateGrant();\n" - lang: python label: Python SDK source: "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\n\ngrant = nylas.grants.update(\n grant_id,\n request_body={\n \"scope\": [\"mail.ready\"]\n }\n)\n\nprint(grant)" - lang: ruby label: Ruby SDK source: "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"\"\n)\n\nrequest_body = {\n scope: [\"mail.read\"]\n}\n\nstatus, _ = nylas.grants.update(grant_id: \"a57cdf3e-6580-4097-9d71-a95e867fb79c\", request_body: request_body)\n\nputs status" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class update_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n\n List scope = new ArrayList<>();\n scope.add(\"mail.read\");\n\n UpdateGrantRequest requestBody = new UpdateGrantRequest.Builder().scopes(scope).build();\n Response grant = nylas.grants().update(\"\", requestBody);\n\n System.out.println(grant);\n }\n}" - lang: kotlin label: Kotlin SDK source: "import com.nylas.NylasClient\nimport com.nylas.models.UpdateGrantRequest\n\nfun main(args: Array) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n val scope = listOf(\"mail.read\")\n val requestBody = UpdateGrantRequest(null, scope)\n val grant = nylas.grants().update(\"\", requestBody);\n \n print(grant)\n}" security: - NYLAS_API_KEY: [] requestBody: required: true description: '' content: application/json: schema: type: object properties: settings: description: Provider-specific settings for the grant. For OAuth providers, this typically contains the `refresh_token`. Nylas replaces the entire `settings` object with the value you provide. example: refresh_token: type: object scope: type: array description: Updates the list of OAuth scopes stored on the grant. This updates only Nylas' record of the scopes — it does not change the actual permissions at the provider. To change provider permissions, the user must re-authenticate through the provider's OAuth consent flow. example: - Mail.Read - Mail.Send - User.Read - offline_access items: type: string responses: '200': content: application/json: schema: type: object properties: request_id: type: string description: ID of the request example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 data: $ref: '#/components/schemas/GrantObject' description: Returns Grant object '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/400' '401': description: Not Authenticated content: application/json: schema: $ref: '#/components/schemas/401' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/404' delete: parameters: - name: grantId schema: example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 type: string in: path required: true operationId: delete_grant_by_id tags: - Manage Grants summary: Delete a grant description: 'Delete an existing grant by ID. You cannot re-authenticate the deleted grant. If you try to re-authenticate it, Nylas creates a new grant instead. **Before deleting a grant, consider whether re-authentication is the better option.** Deleting a grant is permanent: object IDs may change (especially for IMAP providers), sync state resets, and tracking links break. See Handling expired grants for details.' x-code-samples: - lang: bash label: cURL source: "curl --request DELETE \\\n --url 'https://api.us.nylas.com/v3/grants/' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\n// Instantiate Nylas SDK\nconst NylasConfig = {\n apiKey: \"\",\n apiUri: \"\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\n// Define the identifier for the grant\nconst identifier = \"\";\n\n// Function to delete the grant\nasync function destroyGrant() {\n try {\n const response = await nylas.grants.destroy({\n grantId: identifier,\n });\n\n console.log(\"Grant deleted:\", response);\n } catch (error) {\n console.error(\"Error finding grant:\", error);\n }\n}\n\ndestroyGrant();\n" - lang: python label: Python SDK source: "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\n\nresponse = nylas.grants.destroy(\n grant_id\n)\n\nprint(response)" - lang: ruby label: Ruby SDK source: "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: ''\n)\n\nstatus, _ = nylas.grants.destroy(grant_id: \"\")\n\nputs status" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class read_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n DeleteResponse grant = nylas.grants().destroy(\"\");\n \n System.out.println(grant);\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 grant = nylas.grants().destroy(\"\")\n \n print(grant)\n}" security: - NYLAS_API_KEY: [] responses: '200': $ref: '#/components/responses/200-delete' '401': description: Not Authenticated content: application/json: schema: $ref: '#/components/schemas/401' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/404' /v3/grants/me: get: operationId: get_grant_by_access_token tags: - Manage Grants summary: Get current grant description: Gets a grant using current access token x-code-samples: - lang: bash label: cURL source: "curl --request GET \\\n --url 'https://api.us.nylas.com/v3/grants/me' \\\n --header 'Authorization: Bearer ' \\\n --header 'Accept: application/json'" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\n// \"me\" resolves to the grant associated with the access token used on the\n// request. Pair with an ACCESS_TOKEN auth header rather than the API key.\nasync function getCurrentGrant() {\n try {\n const grant = await nylas.grants.find({\n grantId: \"me\",\n });\n\n console.log(\"Current grant:\", grant);\n } catch (error) {\n console.error(\"Error retrieving current grant:\", error);\n }\n}\n\ngetCurrentGrant();\n" security: - ACCESS_TOKEN: [] responses: '200': content: application/json: schema: type: object properties: request_id: type: string description: ID of the request example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 data: $ref: '#/components/schemas/GrantObject' description: Returns Grant object '401': description: Not Authenticated content: application/json: schema: $ref: '#/components/schemas/401' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/404' 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 '404': 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: xyz.not_found_error message: description: Informative error message default: Resource not found type: string example: Resource not found provider_error: description: (OPTIONAL) informative error message from provider's side type: object example: error: invalid_grant provider_error: Bad Request responses: 200-delete: description: Delete Succeeded content: application/json: schema: type: object required: - request_id properties: request_id: type: string description: ID of the request. example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 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.