Update a grant - Manage Grants - API Reference

PATCH

https://api.us.nylas.com/v3/grants/{grantId}

Updates the specified grant's display name, provider settings, scope data, or workspace.

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 provider settings — For non-OAuth providers such as iCloud and IMAP, you can update the credentials and connection settings stored for the grant.
Rename an Agent Account — Set name to change the default From name on messages the account sends.

Omitted top-level fields remain unchanged. Nylas does not deep merge a non-empty settings object with the grant's stored settings. Include all provider-required fields for the settings update. An empty settings object is accepted as a no-op. For more information, see Updating objects.

Works with an API key or an IAM API key with the grants.update permission.

Parameters

Path parameters

grantId*string

Request body

namestring

The display name stored on the grant. An Agent Account uses it as the From name on messages that don't set from and on calendar invitations. The next message uses the new name. An empty string isn't accepted.

Example: "Acme Support"

minLength: 1maxLength: 256

settingsobject

Provider-specific settings for the grant. For OAuth providers, this typically contains the refresh_token. Nylas does not deep merge a non-empty object with stored settings, so include all fields required by the provider for this update. An empty object is accepted as a no-op.

Example: {"refresh_token":"<NEW_REFRESH_TOKEN>"}

scopearray<string>

A list of OAuth scopes to validate for the grant update. When Nylas can read the authoritative scopes from the stored provider grant, it stores and returns those provider-granted scopes instead of the values in this array. This field cannot grant or revoke provider permissions. 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"]

workspace_idstring

The ID of the workspace to move the grant to. The workspace must belong to the same application as the grant. The workspace's domain doesn't need to match the grant's email domain. Omit the field to leave the grant's workspace unchanged. This field can't remove a grant from its workspace. Use remove_grants on the Update workspace assignments endpoint instead.

Example: "abf6ff99-05ad-4c0a-aaf8-400aacf2470a"

Responses

request_idstring

ID of the request

Example: "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90"

dataobject

account_idstring

The v2 Nylas account ID. This field appears only if the grant was created by migrating a v2 connected account.

Example: "df0yq6c9okc6t9j4ejd5nyrt7"

blockedboolean

When true, indicates that the grant is blocked from accessing the Nylas APIs.

Example: false

created_at*integer

When the grant was created, in seconds using the Unix timestamp format.

Example: 1617817109

emailstring

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: "[email protected]"

grant_statusstring

Specifies whether the grant is valid or the user needs to re-authenticate.

invalidvalid

Example: "valid"

id*string

A unique identifier for the grant.

Example: "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47"

ipstring

The user's client IP address. Mostly useful for Hosted OAuth.

Example: "1.1.1.1"

namestring

The user's display name.

Example: "Nyla"

provider*string

The provider that the user authenticated with.

ewsgoogleicloudimapmicrosoftvirtual-calendaryahoozoomnylas

Example: "microsoft"

provider_user_idstring

The user's provider ID. This field might be changed at any time by the provider.

Example: "b16f171c-6640-4edd-a598-e507b546d841"

scope*array<string>

An array of granular scopes associated with the grant. If none are specified, Nylas uses the default scopes from the connector.

Example: ["Mail.Read","User.Read","offline_access"]

settingsobject

A list of settings associated with the grant. The contents of this object might differ between grants or depending on the provider.

email_aliasesarray<string>

An array of found email aliases for this grant. Only returned if special query parameter expose_aliases for Get Grant is used and set to true. Applicable only for Google and Microsoft grants. For Microsoft, aliases require a Microsoft 365 / Exchange Online mailbox. Free Outlook.com (consumer) accounts have no aliases to expose, so this field is omitted from the response even when expose_aliases=true.

Example: ["[email protected]","[email protected]"]

statestring

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_atinteger

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_agentstring

The user's client or browser information. Mostly useful for Hosted OAuth.

workspace_idstring

The ID of the workspace the grant belongs to, if any. Nylas always returns this field for Agent Accounts. For grants from other providers, Nylas omits it when the grant is in the application's default workspace and returns it when the grant is in any other workspace.

Example: "abf6ff99-05ad-4c0a-aaf8-400aacf2470a"

credential_idstring

The ID of the Credential the grant is associated with. Grant will use this Credential for provider communication.

Example: "c123f8e1a-eb1c-41c0-b6a6-d2e59daf7f47"

curl --request PATCH \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --data '{ "settings": { "refresh_token": "<NEW_REFRESH_TOKEN>" }, "scope": ["Mail.Read", "Mail.Send", "User.Read", "offline_access"] }'