Nylas Manage Grants API

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](/docs/v3/auth/hosted-oauth-apikey/). - Using [Hosted OAuth and an access token](/docs/v3/auth/hosted-oauth-accesstoken/), with [optional PKCE](/docs/v3/auth/hosted-oauth-accesstoken/#create-grants-with-oauth-2.0-and-pkce) for additional security. - Using [Bring Your Own Authentication](/docs/v3/auth/custom/). - Using a special [bulk auth grant](/docs/v3/auth/bulk-auth-grants/) (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. ⚠️ If message tracking events occur while a grant is out of service for more than 72 hours, you cannot backfill the notifications. This includes message.opened, message.link_clicked, and thread.replied notifications. ## 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](/docs/reference/notifications/#grant-notifications).