alter grants

A grant is an authorization that says “this end-user (or agent) can use credential X on this app.” Two kinds exist — OAuth grants (provider-issued tokens) and managed-secret grants (developer-stored credentials). list shows both kinds; this namespace’s revoke implementation revokes OAuth grants only. Revoke a managed-secret grant with alter managed-secrets grants revoke.

alter grants list   --app <app-id-or-name> [--status ...] [--provider ...] [--app-user ...] [--search ...]
alter grants revoke --app <app-id-or-name> --grant <grant-id> [--reason "..."] [--yes]

list returns polymorphic rows: each carries a grant_type discriminator (oauth or managed_secret).

list needs dashboard_grants:read (in the default alter auth login scope set). revoke needs dashboard_grants:admin and is not in the default set — re-run alter auth login with --scopes and include the full set of scopes you want on the new PAT, plus dashboard_grants:admin. Note that --scopes REPLACES the default set rather than appending to it, so list every scope you need explicitly. Grant revocation is recoverable (re-consent restores access through the OAuth flow), which is why it sits on the standard :admin tier rather than a separate :delete tier.

list

Flag	Default	Description
--app <app-id-or-name>	—	App ID or name. Falls back to ALTER_APP_ID or the linked workspace (both UUID only).
--status <status>	all	active, expired, or revoked. Case-sensitive.
--provider <id>	all	Filter by provider. OAuth: the provider id (e.g. google, github). Managed secret: the per-secret slug (e.g. stripe-production), unique per app.
--app-user <uuid>	all	Filter to one end-user.
--search <text>	—	Substring match on user identifier or display name (max 100 chars; backend-side).
--limit <n>	100	Page size (1–1000).
--offset <n>	0	Pagination offset. Clamps to 10,000 with is_truncated=true.
--output <format>	table	json, jsonl, or table.

# All active grants on an app
alter grants list --app <app-id-or-name> --status active

# Just one provider, as newline-delimited JSON for piping
alter grants list --app <app-id-or-name> --provider google --output jsonl

The default table view includes three delegation-tree columns alongside ID / TYPE / PROVIDER / STATUS / USER / CREATED:

Column	Meaning
DEPTH	Hop distance from the credential root: 0 is a root grant (minted at consent), 1 a first-hop delegation to an agent, 2+ an onward agent→agent delegation.
DELEGABLE	yes when the grant may be re-delegated onward by its holder (opt-in at every hop); no for a leaf.
NARROWED	The provider-scope subset a delegated grant is clamped to (comma-separated), or full when it inherits the parent/credential scope unrestricted. A narrowed grant is proxy-only.

In --output json / jsonl the same data appears as depth, delegable, parent_grant_id, and scope_constraint fields — parent_grant_id (null for a root) lets scripts reconstruct the whole delegation tree from the flat list.

Every output format emits the grant rows themselves — --output json is the rows array, matching every other list command. When more grants remain, the command prints the next --offset to run on stderr, so a | jq pipeline keeps clean data on stdout.

revoke

Revoke an OAuth grant immediately. This cascades to active agent delegations under the grant, then best-effort-deletes its stored provider token. A managed-secret grant ID is not accepted here; use alter managed-secrets grants revoke.

Flag	Default	Description
--app <app-id-or-name>	—	App ID or name. Falls back to ALTER_APP_ID or the linked workspace (both UUID only).
--grant <grant-id>	—	Grant ID (required).
--reason "<text>"	—	Optional operator-supplied reason recorded on the audit row.
--yes	—	Skip the interactive y/N prompt (use in scripts).

alter grants revoke --app <app-id-or-name> --grant <grant-id> \
  --reason "user requested deletion" --yes

Recipes

Find expired grants for a user

alter grants list --app <app-id-or-name> --app-user <uuid> --status expired

Revoke every grant for a single provider

alter grants list --app <app-id-or-name> --provider github --status active --output jsonl \
  | jq -r '.id' \
  | xargs -I{} alter grants revoke --app <app-id-or-name> --grant {} --yes

Related

• Audit logs — every revoke produces an audit row with actor_source=pat when CLI-driven
• alter audit grant-events — query the same revocations after the fact