# List and revoke connected grants

Source: https://developer.nylas.com/docs/cookbook/use-cases/build/list-revoke-grants/

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?

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.

```bash
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?

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.

```bash
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](/docs/cookbook/use-cases/build/handle-grant-expiry/).

## Manage grants from the terminal

The [Nylas CLI](https://cli.nylas.com/docs/commands) lists, removes, and revokes connected accounts: `nylas auth list` shows every grant the CLI has stored with its ID and provider, `nylas auth remove` drops one from your local config, and `nylas auth revoke` permanently revokes it on the server.

```bash
# List connected grants
nylas auth list

# Remove a grant from local config (keeps it on the server)
nylas auth remove <grant-id>

# Permanently revoke a grant on the server
nylas auth revoke <grant-id>
```

Watch the distinction: `auth remove` only clears your local config, while `auth revoke` is the true server-side revoke that disconnects the account for good. Grants can come from any of the 6 providers Nylas supports, and `auth list` shows them all. See the [`auth list`](https://cli.nylas.com/docs/commands/auth-list) and [`auth remove`](https://cli.nylas.com/docs/commands/auth-remove) command reference.

## 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](/docs/v3/auth/).

## What's next

- [Handle grant expiry and re-authentication](/docs/cookbook/use-cases/build/handle-grant-expiry/) for recovering invalid grants instead of deleting them
- [Connect user accounts with OAuth](/docs/cookbook/use-cases/build/connect-user-accounts-oauth/) for how grants are created
- [Authentication overview](/docs/v3/auth/) for the full grant model
- [Bulk-authenticate user accounts](/docs/cookbook/use-cases/build/bulk-authenticate-accounts/) to create grants at scale