alter keys

Runtime API keys authenticate application code against Alter. These commands manage the keys for one app.

alter keys list       [--status active|revoked] [--limit ...] [--offset ...]
alter keys statistics [--output json|jsonl|table]
alter keys mint       --name <name> --scopes <list> [--key-type ...] [...]
alter keys show   --key <key-id>
alter keys rotate --key <key-id> [--scopes ...]
alter keys revoke --key <key-id> [--force] [--yes]
alter keys rename --key <key-id> --name <name>

All commands are app-scoped — pass --app <id> (or the app’s name), or link a workspace / set ALTER_APP_ID. list / show / statistics need dashboard_keys:read; mint / rotate / rename need dashboard_keys:write; revoke needs dashboard_keys:admin.

Note

mint and rotate require an organization admin. An API key is a machine credential with programmatic access to the application’s credential vault, so issuing one — with mint, or with rotate (which returns a fresh plaintext successor and can change the scope set) — is an organization-admin action. The token used must belong to an organization admin (in addition to carrying dashboard_keys:write); a non-admin’s token is rejected. revoke and rename are not restricted this way. Have an admin mint the automation token once; CI then keeps working under it.

Warning

Plaintext keys are shown once — on mint and rotate. The CLI never caches them; re-running a command shows metadata only, not the secret. Capture the value when it’s printed.

list

Flag	Default	Description
--status <status>	all	Client-side filter on the fetched page: active means revoked_at is null (including rotated keys still in grace); revoked means it is set.
--limit <n>	200	Page size (1–1000).
--offset <n>	0	Pagination offset.

alter keys list --status active

All output formats emit the filtered current-page rows as an array/row stream, not the pagination envelope. Filtering happens after the page is fetched.

The table includes a RATE LIMIT column showing the ceiling each key is actually held to and which layer produced it — 1000 (key) for a per-key value chosen at mint time, 1000 (org) for the organization’s per-key maximum, and 1000 (platform) for the platform default. The distinction matters when capacity-planning: a platform default can move, a per-key value cannot. A — means the backend did not report a ceiling — unknown, never unlimited. 500 (?) means the backend reported the effective ceiling but omitted or used an unrecognized source; the number remains usable while its controlling layer is unknown.

statistics

Read-only quota summary for the app’s keys — active, rotated_in_grace, total, and max_allowed. Useful for a CI preflight before minting (e.g. fail the job if active is near max_allowed).

Flag	Default	Description
--output <format>	json	json, jsonl, or table.

alter keys statistics --output table

mint

Mint a new scoped key. --name and --scopes are required unless you supply a full JSON body with --input.

Flag	Required	Description
--name <name>	yes	Display name.
--scopes <list>	yes	Comma-separated Alter scopes (e.g. grants:read,agents:read).
--key-type <type>	no	runtime (default — an SDK key) or agent (an agent key).
--cidr <list>	no	Comma-separated CIDR allowlist. Catch-all ranges are rejected: a single /0, a split-range set whose union covers a whole address family (e.g. 0.0.0.0/1,128.0.0.0/1), and an entry covering the entire IPv4-mapped-IPv6 block (::ffff:0.0.0.0/96). For an unrestricted key, omit the flag entirely.
--rate-limit-rpm <n>	no	Per-key requests-per-minute cap (1–100000). When the organization sets a per-key maximum, a higher value is rejected at mint time. Omitted, the organization’s per-key maximum becomes this key’s limit — it replaces the platform default rather than capping it, so the effective limit can be well above 1,000. With no per-key value and no organization maximum, the platform default of 1,000 requests/minute applies. See Errors for the full precedence table.
--expires-in <duration>	no	Relative expiry, e.g. 30d, 12h, 5m. Mutually exclusive with --expires-at.
--expires-at <iso>	no	Absolute ISO 8601 expiry. Mutually exclusive with --expires-in.
--input <path>	no	JSON body from a file (@path) or stdin (-); replaces the per-field flags.

alter keys mint --name "prod-worker" --scopes grants:read,agents:read --expires-in 90d

show

alter keys show --key <key-id>

rotate

Issue a new secret for an existing key. The new plaintext is returned once; the old key enters a grace period until it’s revoked. --scopes optionally changes the scope set (defaults to the current one).

alter keys rotate --key <key-id>

revoke

Revoke a key immediately. This cascades to any derived keys. Revocation is recoverable — mint a new key — so the CLI asks a simple y/N (skip with --yes).

--force overrides the last-active-key guard, which otherwise blocks revoking an agent’s only active key (doing so leaves the agent unusable until a fresh key is minted).

alter keys revoke --key <key-id>
alter keys revoke --key <key-id> --yes --force   # CI, deliberate

rename

Change a key’s display name. Cosmetic only — it does not rotate the secret.

alter keys rename --key <key-id> --name "prod-worker-east"

Recipes

Mint the Developer Portal’s Backend service template from the CLI

alter keys mint --name backend-service \
  --scopes grants:write,providers:read,tokens:retrieve,proxy:execute,connect:initiate,audit:emit

This is the CLI equivalent of choosing Backend service under App → API Keys → Create key. OAuth Connect requires connect:initiate and grants:write together; providers:read powers SDK provider discovery, and audit:emit lets direct SDK calls record provider outcomes.

Rotate a key without downtime

# 1. Rotate — a new plaintext is printed once; the old secret keeps
#    working during its grace window.
alter keys rotate --key <key-id>
# 2. Roll the new value out everywhere and confirm healthy traffic.
# 3. Revoke the superseded key once nothing depends on it.
alter keys revoke --key <key-id> --yes

Mint a short-lived key for a CI job

alter keys mint --name ci-deploy --scopes grants:read,agents:read --expires-in 1h

Related

• alter agents — managed-agent identities and their own keys
• API keys, Scopes