Revoke an AI Agent's Email Access

How do you revoke an AI agent's access to a user's email?

Revoke an agent's access to a user's mailbox by deleting the OAuth grant that backs it. List the grants to find the right ID, run nylas auth revoke against that ID, and the agent loses all read and send access to that inbox at once. The grant is the unit of access, so revoking it is the complete and final off switch for that one connection.

Revocation matters because an unrevoked grant keeps working. An OAuth access token stays valid for up to 3,600 seconds after a user thinks they've disconnected, and the refresh token behind it can mint new ones indefinitely. Revoking the grant invalidates both, which is the only way to guarantee the agent can no longer reach that mailbox.

When should you revoke a user's email grant?

Revoke a grant whenever the agent's authorization to a mailbox should end: a user disconnects the integration, an employee offboards, a customer churns, or a security incident demands cutting access fast. Each event maps to one grant, so the action is the same every time — find it and revoke it.

Data-deletion requests are the highest-stakes case. The GDPR right to erasure (Article 17) gives a user the right to have their data removed, and revoking the grant is the first step: it stops the agent from reading any more of their mail. Article 12 sets a one-month deadline to act on an erasure request, but you don't want to use it — wire revocation into your disconnect webhook so it fires the moment a user opts out, not on a nightly batch hours later.

How do you find the grant ID to revoke?

List the grants and match on the user's email or provider. The nylas auth list --json command returns every connected grant — up to five on the free tier — with its ID, email, and provider as structured data your offboard script can filter. Pipe it through jq to match the one grant for the disconnected user in a single pass.

# List grants and find the one for the disconnected user
nylas auth list --json

# Filter to one user's grant by email
nylas auth list --json | jq '.[] | select(.email == "user@example.com")'

Store the grant ID against the user in your own database at connect time. Then an offboard never needs to search at all — you already hold the exact ID to revoke, which turns the lookup above into a safety check rather than a dependency.

How do you confirm the grant is fully revoked?

Remove the grant, then list again and confirm it's gone. The nylas auth revoke command deletes the grant and the tokens cached for it, so the agent can no longer authenticate to that mailbox. RFC 7009 defines the OAuth token-revocation flow that produces this end state. A second auth list that no longer shows the grant is your proof the access is gone.

# Revoke the grant by ID, then verify it's gone
nylas auth revoke grant_abc123
nylas auth list --json   # the revoked grant no longer appears

Revoking the grant locks the agent out everywhere, not just locally: the grant is gone on the server, so its next email list has nothing to authenticate with and fails closed with a 401 Unauthorized on the very next API call, the end state Google describes in its OAuth 2.0 web-server flow. Don't confuse it with nylas auth remove, which only drops the grant from local config and leaves it valid on the server — use revoke when the goal is to end access.

How is revoking a user grant different from deleting an agent account?

Revoking a grant and deleting an agent account are two different off switches for two different things. A grant is a user's mailbox connected through delegated OAuth — revoke it and the user keeps their inbox, the agent just loses access. An agent account is an inbox the agent owns — delete it and the mailbox itself is gone.

Use nylas auth revoke when a user disconnects their own mailbox, and nylas agent account delete when you're tearing down an agent's own identity. A revoked grant can be reconnected in under a minute if the user comes back; a deleted agent account is permanent. Picking the wrong one either leaves access live or destroys a mailbox you meant to keep, so match the command to what actually needs to end.

Next steps

• Agent Account vs Delegated OAuth — the difference between a user grant and an agent's own inbox, in depth
• Manage the Agent Account Lifecycle — create, rotate, pause, and delete an agent's own account
• Fix the Invalid Grant Error — diagnose a grant that broke on its own, before you remove it
• Build a GDPR Data-Request Agent — the erasure-request intake flow that triggers a grant removal
• Full command reference — every nylas auth subcommand and flag