Your application accumulates grants as users connect their accounts, and you need to see them and clean them up: show a user which mailbox they connected, or disconnect an account when someone leaves. That’s reading and deleting grants, the records that represent each connection.
The Nylas API lists every grant on your application and deletes one on request. This recipe covers listing with filters and the one call that permanently disconnects an account.
How do I list connected grants?
Section titled “How do I list connected grants?”Send a GET /v3/grants request. It returns every grant on your application, whatever the provider, each with 4 fields: its id, the connected email, the provider, and the grant_status. Filter with query parameters like provider=google or grant_status=invalid and page with limit and offset. The request below lists the first 3 Google grants.
curl --request GET \--url 'https://api.us.nylas.com/v3/grants?limit=3&provider=google' \--header 'Accept: application/json' \--header 'Authorization: Bearer <NYLAS_API_KEY>' \How do I revoke a grant?
Section titled “How do I revoke a grant?”Send a DELETE /v3/grants/{grant_id} request to disconnect an account permanently. This is the right call when a user removes their account or leaves your product, and it stops all access and webhooks for that grant immediately. Deletion is final, unlike the up to 72 hours of event backfill an expired grant gets when re-authenticated. The request below revokes one grant.
curl --request DELETE \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \Delete only for an intentional disconnect, never to fix an expired grant: deletion is permanent and loses sync state and object IDs, so an expired grant should be re-authenticated instead, as covered in handle grant expiry.
Things to know about managing grants
Section titled “Things to know about managing grants”A couple of points keep this safe. Listing supports provider and grant_status filters plus limit and offset paging, so a large application can page through grants rather than pulling them all at once. The grant_status field is valid or invalid, telling you a grant’s health before you act on it.
The hard rule is that DELETE is irreversible: a new grant for the same user gets a new ID, and on IMAP every message ID changes too, so reserve deletion for genuine disconnections. Re-authenticating an expired grant instead replays up to 72 hours of missed events. For the full grant model, see the authentication overview.
What’s next
Section titled “What’s next”- Handle grant expiry and re-authentication for recovering invalid grants instead of deleting them
- Connect user accounts with OAuth for how grants are created
- Authentication overview for the full grant model
- Bulk-authenticate user accounts to create grants at scale