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 (a stored key: the developer’s, or an end user’s own). list shows both kinds and revoke revokes either, by id. alter managed-secrets grants revoke revokes a managed-secret grant too.

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. Revoking a managed-secret grant here also needs dashboard_secrets:admin, the scope alter managed-secrets grants revoke needs; without it the command exits 7. Grant revocation is recoverable (re-consent restores access), 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-or-slug>	all	Filter by provider. OAuth: the provider id (e.g. google, github). Managed-secret: the managed-secret provider’s slug (e.g. stripe-production), unique per app, shown in the SLUG column and as managed_secret_slug in JSON. One value can match both an OAuth provider id and a managed-secret provider’s slug (a managed-secret provider named “GitHub” gets the slug github), and then returns both kinds: filter on grant_type before acting on every row.
--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

# One managed-secret provider's grants, by its slug
alter grants list --app <app-id-or-name> --provider stripe-production

A managed-secret row’s provider_id is the template its provider was created from (managed_secret for a custom provider), so two providers of one template share it; filter by the row’s managed_secret_slug, which names exactly one provider. On an OAuth row managed_secret_slug is null and provider_id is the value --provider matches.

The default table view includes three delegation-tree columns alongside ID / TYPE / PROVIDER / SLUG / STATUS / USER / CREATED (SLUG is a managed-secret provider’s slug, shown in full, — on an OAuth row):

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.

Each JSON row also says whose grant it is and how it may be used: user_rule_present is true when a limit the end user set applies to the grant, which makes it proxy-only (raw retrieval is refused with user_limits_require_proxy). On a managed-secret row, credential_kind is developer or end_user (an end user’s own key), and user_owned is true for an end user’s own key or a delegation a user consented to: you can revoke it, and nothing else.

The API HOST column shows where an OAuth connection’s provider API lives, for providers whose API host depends on the connected account or the provider environment: the QuickBooks production or sandbox Accounting host that confirmed the company, a Salesforce org’s instance URL, or Ramp’s production or sandbox API host. It shows — for providers that record no host (one fixed API 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 or managed-secret grant immediately. This cascades to active agent delegations under the grant, then best-effort-deletes its stored provider token. A managed-secret grant is revoked exactly as alter managed-secrets grants revoke revokes it, and needs dashboard_secrets:admin as well. Revoking the grant of an end user’s own managed-secret key also revokes and destroys the key: the user stores it again through Connect. This command takes only a grant id, so its prompt names that consequence for any grant; alter managed-secrets grants revoke reads the grant first and prints exactly what its revoke destroys, with every delegation it revokes.

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 OAuth provider

--provider github also matches a managed-secret provider whose slug is github, and revoking the grant of an end user’s own managed-secret key destroys the key. Keep only the OAuth rows before revoking:

alter grants list --app <app-id-or-name> --provider github --status active --output jsonl \
  | jq -r 'select(.grant_type == "oauth") | .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