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.

The API HOST column shows where an OAuth connection’s provider API lives, for providers that serve each account from its own host: the QuickBooks production or sandbox Accounting host that confirmed the company, or a Salesforce org’s instance URL. It shows — for providers with one fixed host and for connections made before Alter recorded the host (reconnect to capture it). In --output json / jsonl the value is the api_base_url field, a full https:// origin or null; build provider request URLs from it rather than from a configured or guessed host.

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