Update a grant - Manage Grants - API Reference

PATCH

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

Updates the specified grant's provider settings or scope data.

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.

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.

NYLAS API KEY

Parameters

Path parameters

grantId*string

Request body

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"]

Responses

request_idstring

ID of the request

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

dataobject

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"] }'