Update a grant - Manage Grants - API Reference

PATCH

/v3/grants/{grantId}

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.

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 replaces the entire settings object with the value you provide.

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

scopearray<string>

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

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