Grants are the main objects that power Nylas, representing your users’ authenticated accounts and the scopes they’ve approved for your project. This page describes how to manage grants throughout their lifecycle.
What are grants?
A grant is a record of a user’s account authenticating successfully with their provider and “granting” your project access to specific parts of their account’s email inbox and calendar. This access is represented by the scopes they approve when they authenticate.
A valid grant records a unique ID for the user, the scopes that they approved during authentication, and some information about access tokens.
Each grant belongs to a specific connector, in a specific Nylas application. A grant can’t be associated with multiple connectors, providers, or Nylas applications.
Create a grant
Nylas offers multiple ways to create grants:
- Using Hosted OAuth with an API key.
- Using Hosted OAuth with an access token.
- Using Custom Authentication.
- Using IMAP authentication.
Be sure to choose the authentication method that’s right for you before you start developing your project.
Re-authenticate a grant
Grants can become invalid for many reasons (for example, the user changed their password or revoked access to your project). When this happens, Nylas loses access to the user’s data and stops sending notifications about changes to their objects. You need to re-authenticate the user’s grant to restore access.
When the user re-authenticates successfully, Nylas looks at when their grant was last valid. 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, so be sure to set up your webhook destination to handle notifications at scale.
If the grant was out of service for more than 72 hours, Nylas doesn’t send backfill notifications. When this happens, you can look for the appropriate grant.expired and grant.updated notifications, then 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 can’t backfill the notifications. This includes message.opened, message.link_clicked, and thread.replied notifications.
Re-authenticating a grant follows the same flow and uses the same endpoints as the initial authentication process. When Nylas receives an authentication request, it checks to see if a grant is already associated with the user’s email address. If one exists, Nylas re-authenticates the grant instead of creating a new one.
Monitor grants for invalid state
You can use one of the following methods to monitor grants for an invalid state:
- (Recommended) Subscribe to
grant.*notifications to stay up to date with status changes. If you receive agrant.expirednotification, the affected grant needs to be re-authenticated. - Make poll requests to the Get all grants endpoint and check each
grant_status. - Log in to the Nylas Dashboard and select Grants in the left navigation. Grants that need to be re-authenticated are marked as Invalid.
Delete a grant
If a user no longer needs access to your project, you can delete their grant by making a Delete Grant request. Nylas also revokes the refresh token and any access tokens associated with the grant.
If you’re deleting a Google grant, Nylas also revokes its provider token. For all other providers, the provider tokens remain active.
When you make a Delete Grant request, Nylas deletes the grant and stops sending notifications for it. You can’t re-authenticate the deleted grant. If you try to re-authenticate it, Nylas creates a new grant instead.
You can also delete a grant in the Nylas Dashboard:
- Select Grants from the left navigation.
- Find the grant that you want to delete and click the options symbol (
⋮) beside it. - Click Delete and confirm that you want to delete the grant.
Revoked versus deleted grants
A grant can be revoked in multiple scenarios (for example, the user changed their password). When this happens, the grant’s token is invalidated and the user can’t access your project until they re-authenticate. Nylas also can’t update the data for a revoked grant.
Nylas stores the data for grants as long as they’re associated with your application, even if they’re revoked. Nylas deletes a grant’s data only when the grant itself is deleted.
Nylas bills for all grants associated with your application, even if they’re revoked. When you delete a grant, your organization is no longer billed for it. For more information, see our billing documentation.