Manage Grants

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. They also represent access granted to your application for certain resources.

There are several ways to create grants:

• Using Hosted OAuth and an API key.
• Using Hosted OAuth and an access token, with optional PKCE for additional security.
• Using Bring Your Own Authentication.
• Using a special bulk auth grant (also called a "service account").

You can re-authenticate grants using any of these methods, and Nylas handles all the re-authentication logic internally.

Grant expiry

Grants, and their access tokens and refresh tokens are controlled by the provider, not Nylas. Nylas can request that the provider invalidate or revoke a grant, but can't prevent the provider from expiring a grant.

Usually when a provider expires a grant it is after a period of inactivity, and the provider expires the associated access token for security reasons. To prevent grants from expiring, encourage users to actively engage with their accounts and regularly refresh the access token with a valid refresh token.

Re-authentication and notifications

Grants can become invalid for many reasons (for example, the user changing their password). When a grant becomes invalid, the user must re-authenticate to access your application.

When a grant becomes invalid, Nylas loses access to the affected user's data and stops sending notifications about changes to its objects. When the user re-authenticates, Nylas looks at when their grant last authenticated successfully. If it was less than 72 hours ago, Nylas looks for any changes that happened since the last successful sync and sends you notifications about those events. This can be a lot of notifications.

If the grant was out of service for more than 72 hours, Nylas doesn't send backfill notifications. When this happens, look for the grant.expired and grant.updated notifications and query the Nylas APIs for objects that changed between those timestamps.

Grant limitations

When working with grants, keep the following limitations in mind:

• You can re-authenticate a grant to add new scopes, remove scopes, or extend its expiry date.
• Each grant belongs to a specific Nylas connector (because they come from a specific provider), in a specific Nylas application. A grant cannot be associated with multiple connectors or applications.
• Grants expire after a pre-defined period of time. When this happens, they must be re-authenticated.

Grant notifications

You can subscribe to the following triggers so Nylas notifies you about changes to your users' data:

• grant.created
• grant.updated
• grant.deleted
• grant.expired

For more information, see the Grant notification schemas.