Virtual keys

A virtual key is the credential your application uses to call the gateway — what you hand to a service instead of a real vendor key. Master vendor keys stay sealed in the catalog; virtual keys are vendor-agnostic, scoped, revocable, and can expire.

Dashboard: Operate ▸ Virtual keys. API: POST /admin/keys and friends (see Admin API). Requires ISSUE_KEYS (user and up).

Anatomy of a key

A 256-bit token with an sk- prefix, presented by applications as Authorization: Bearer sk-… or x-api-key: sk-….
Stored only as a SHA-256 hash. The secret is shown once, at issue time; afterwards the list shows a non-secret hint (a prefix), the scope, and the status.
Carries its placement — org, optional team, optional project — so the whole scope chain is known the instant a request arrives. Placement is fixed at issue time.
Optionally carries a TTL (ttlSeconds), after which it stops authenticating.

Issuing a key

Click Issue key (or POST /admin/keys).
Choose the placement: the org, and optionally a team and a project. This decides which budgets, rate limits, and guardrail policies apply to it.
Give it a label (alias) so you can recognize it later.
Issue, and copy the secret now — only its hash is stored, so it can never be shown again.

Command

curl -s -u admin:PASSWORD -X POST https://aam.example.com/admin/keys \
  -H "Content-Type: application/json" \
  -d '{"alias": "checkout-service", "teamId": "TEAM-UUID", "ttlSeconds": 7776000}'

Placement rules and limits

Placement authority. Placing a key directly at the org level (no team) draws on the org's shared pool, so it requires budget authority (MANAGE_BUDGETS — admin/owner) or the platform admin. A regular member must place the key in a team they belong to. This stops a member from minting org-level spend.
Per-scope key-count caps. An always-on ceiling limits how many keys a scope may hold (default 200), plus admin-set caps via the key-limits API (POST /admin/key-limits). Hitting the cap returns a clear 409.
Visibility is scoped. A plain member sees only their teams' keys; VIEW_SECURITY sees the whole org; the platform admin sees all.

Key lifecycle

State	How it happens	Reversible?
Active	Issued	—
Suspended	`POST /admin/keys/{id}/suspend`, or SOAR quarantine	Yes — `unsuspend`
Expired	TTL elapsed	No (issue a new key)
Revoked	`POST /admin/keys/{id}/revoke`	No

Revocation is immediate: the hash is marked revoked and the next request with that key is rejected. Suspension is the reversible variant used by automated containment — see SIEM, UEBA & SOAR and the Contain a leaked key guide.

Operational practices

Issue one key per application or agent, not per person — keys are workload identities, and per-workload keys make the audit trail, budgets, and containment meaningful.
Set a TTL on keys for short-lived workloads, and stack a KEY-scope budget or rate limit on anything experimental.
Rotate by issuing a new key, cutting the application over, then revoking the old one — issuance is cheap by design.

Quickstart — mint a key and make a request in five minutes.
Budgets & rate limits — capping a single key.