Skip to content
Skip to main content

Handle grant expiry and re-authentication

A user’s connection breaks: they change their password, an admin forces a token refresh, or the provider expires the token. Their grant goes invalid, and your app’s calls start failing. An expired grant isn’t a bug in your integration, though. Grants expire as part of normal operation, and almost all of them are recoverable.

The fix is re-authentication, not deletion. Re-authenticating refreshes the provider tokens while keeping the same grant ID, object IDs, sync state, and tracking links. This recipe covers how to detect the expiry and how to recover cleanly.

How do I detect an expired grant?

Section titled “How do I detect an expired grant?”

Use two signals together. Subscribe a webhook to the grant.expired trigger for proactive alerts: Nylas detects expired grants through sync health checks, which can take up to 10 minutes. Then handle 401 responses on every API call to catch an expiry instantly, since a grant you aren’t actively querying could otherwise go unnoticed for hours.

The request below subscribes a webhook to the grant.expired trigger.

Don’t poll GET /v3/grants/{id} in a loop to check status; it’s inefficient and counts against your rate limits. Lean on the webhook plus 401 handling instead.

How do I re-authenticate a user?

Section titled “How do I re-authenticate a user?”

Send the user back through the same authentication flow you used to connect them the first time. The endpoints are identical: when Nylas receives an auth request for an email that already has a grant, it re-authenticates that grant instead of creating a new one. The grant ID and all object IDs stay the same.

There’s a recovery bonus: if the grant was invalid for less than 72 hours, Nylas re-sends the webhook notifications you missed during the outage. That backfill can be a large burst, so make sure your endpoint can absorb the spike. See connect user accounts with OAuth for the auth flow.

Why shouldn’t I delete an expired grant?

Section titled “Why shouldn’t I delete an expired grant?”

Deleting an expired grant and recreating it causes permanent, irreversible data loss, so always re-authenticate instead. A new grant gets a new ID, which breaks every reference your app stored. For IMAP providers it’s worse: Nylas hashes message and thread IDs from the grant ID, so a new grant changes every message ID.

You also lose the webhook backfill, which only covers the first 72 hours, because a fresh grant has no prior sync state to compare against. The expired grant record stays intact in Nylas and is fully recoverable, so there’s no reason to delete it. See grant lifecycle for the full consequences.

What’s next

Section titled “What’s next”