Sign in
Manage Grants

Update a grant

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.

patch/v3/grants/{grantId}

Path parameters

grantIdstring required
Example:5967ca40-a2d8-4ee0-a0e0-6f18ace39a90

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.

scopestring[]

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 request

{
  "settings": {
    "refresh_token": "<NEW_REFRESH_TOKEN>"
  },
  "scope": [
    "Mail.Read",
    "Mail.Send",
    "User.Read",
    "offline_access"
  ]
}

Response

Returns Grant object

request_idstring

ID of the request

Example response

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "account_id": "df0yq6c9okc6t9j4ejd5nyrt7",
    "created_at": 1617817109,
    "email": "nyla@example.com",
    "grant_status": "valid",
    "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
    "ip": "1.1.1.1",
    "name": "Nyla",
    "provider": "microsoft",
    "provider_user_id": "b16f171c-6640-4edd-a598-e507b546d841",
    "scope": [
      "Mail.Read",
      "User.Read",
      "offline_access"
    ],
    "email_aliases": [
      "email_alias1@example.com",
      "email_alias2@example.com"
    ],
    "state": "my-state",
    "updated_at": 1617817109,
    "workspace_id": "abf6ff99-05ad-4c0a-aaf8-400aacf2470a",
    "credential_id": "c123f8e1a-eb1c-41c0-b6a6-d2e59daf7f47"
  }
}

Changes