API Keys CLI

Use provon api-keys to manage project API keys and their Gateway usage policies. These commands require a project-scoped credential: select one with provon project use , pass --project , or set PROVON_PROJECT_ID.

View as Markdown Open the plain-text version of this page.

Prerequisites#

Authenticated CLI (see Authentication).
The active project id.
A credential with workspace:read to list keys; key management requires the project's project:apiKeys:write permission.

List API Keys#

provon api-keys list

The list shows key metadata (id, name, status, capabilities, created time). Plaintext values are never returned by list or get responses.

Create An API Key#

provon api-keys create --name "CI deployment"

Restrict capabilities with a comma-separated list:

provon api-keys create \
  --name "Read-only telemetry" \
  --capabilities telemetry:read

When --capabilities is omitted, the key receives the default capability set:

Default capability	Covers
`telemetry:ingest`	OTLP uploads from `ingest sync` and live hooks
`telemetry:read`	Trace read commands
`diagnostics:read`	Finding and rule read commands
`gateway:invoke`	Proxied Gateway requests
`model-pricing:read`	Model pricing lookups
`workspace:read`	Organization and project read commands

Additional grantable capabilities:

Capability	Typical use
`diagnostics:write`	Finding review updates, handoffs, rule changes, backfill
`gateway:manage`	Provider, routing, and guardrail administration
`mcp:invoke`	Calling federated MCP tools
`mcp:manage`	MCP server, credential, and policy administration
`model-pricing:write`	Pricing record writes
`workspace:write`	Organization and project writes
`models:manage`	Model catalog administration

Success Check#

The create response returns the plaintext key (prefixed sk_provon_) once. Save it immediately in a secret manager; it cannot be recovered later. Verify it works:

PROVON_API_KEY="<plaintext-key>" provon traces list

Rename An API Key#

provon api-keys rename <key-id> --name "Updated name"

Revoke An API Key#

provon api-keys revoke <key-id>

Revocation takes effect on subsequent requests; in-flight requests are not interrupted.

Usage Policies#

Usage policies limit how an API key consumes Gateway resources. Each policy is a rate limit or a budget, scoped to the whole key or, with --model, to one model on that key.

Create a policy:

provon api-keys usage-policies create <key-id> \
  --metric requests \
  --mode rate_limit \
  --limit 1000 \
  --window hour

Limit the policy to a single model:

provon api-keys usage-policies create <key-id> \
  --model gpt-4o \
  --metric cost_usd \
  --mode budget \
  --limit 50 \
  --window month

Policy Reference#

Flag	Values	Notes
`--metric`	`requests`, `tokens`, `cost_usd`	Required
`--mode`	`rate_limit`, `budget`	Required
`--limit <n>`	Positive integer	Required; units match the metric
`--window`	`minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`, `custom`, `lifetime`	Required
`--model <name>`	Model id	Omit to apply to the whole key
`--custom-window-seconds <n>`	Positive integer	Required when `--window custom`
`--enabled`	Flag; default enabled at creation	—

For a custom window:

provon api-keys usage-policies create <key-id> \
  --metric cost_usd \
  --mode budget \
  --limit 50 \
  --window custom \
  --custom-window-seconds 86400

Update a policy:

provon api-keys usage-policies update <key-id> <policy-id> \
  --limit 2000 \
  --window day \
  --enabled false

--enabled accepts true or false; at least one field must be supplied.

Delete a policy:

provon api-keys usage-policies delete <key-id> <policy-id>

Troubleshooting#

Symptom	Likely cause	Fix
`requireProjectId` error	No active project	`provon project use <id>` or pass `--project <id>`
`HTTP_403` on create/revoke	Missing `project:apiKeys:write` permission	Use an owner/admin session or a key with write access
Key works for `traces list` but not `findings update`	Missing `diagnostics:write`	Recreate the key with the required capability
Policy rejects traffic immediately	`--limit` too low or wrong `--metric` units	Review with `provon api-keys list` and update the policy
`--window custom` rejected	Missing `--custom-window-seconds`	Supply a positive second count
Plaintext key lost	Only returned at creation	Revoke and create a replacement key