API access
Scripts and bots get their own admin credentials, scoped to a subset of what the minter holds. The break-glass admin token never leaves the operator.
Two grant vocabularies reach the same operations:
| Vocabulary | Gates | Detail |
|---|---|---|
| Capabilities | The legacy /admin/* routes | The granular grants behind the roles and bundles operators hold. |
Scopes (<resource>:read, <resource>:write) | The management API (/admin/v1/*) | Derived from the URL. It twins every legacy route, so a role, a bundle, or a scoped key reaches the same operations on both surfaces. GET /admin/v1/me lists the caller's scopes. |
Endpoints and scope tables: API reference.
Scoped admin API keys
For automation against /admin/*, mint an aak_… key from the Agents card on the Users page
(Add agent, then the Admin API access option), or with POST /admin/api-keys
(API reference).
| Property | Posture |
|---|---|
| Explicit subset only | A key is minted with one grant shape: capabilities, or native Management API v1 scopes, each a subset of the minter's own. adminkeys:manage, held by security_admin and owner, gates minting. Scope-minted keys have no capabilities and are v1-only, so they cannot satisfy any legacy /admin/* capability gate. |
| 90-day expiry by default | A longer horizon or no expiry is an explicit mint-time choice. |
| Hash at rest, shown once | The raw key appears once, in the mint response, and the store keeps a SHA-256. Revocation (console or DELETE /admin/api-keys/:id) takes effect on the next request on every replica. Keys survive the minting operator's offboarding, so revoke them as part of it. |
| Audited | Minting and revocation are audit-logged, and every admin write made with a key is attributed as apikey:<id>. |
| Fails closed as infrastructure | If the key store is unreachable, verification answers 503 admin_key_store_unavailable, never a 401, and the break-glass admin key keeps working. |
Capabilities: trace content (observability:read-content), reading an agent's stored key
(clientkeys:secret), content-mode changes (content:manage), SSO configuration (idp:manage),
the identity mode (identity:manage), running updates (update:run), and key management itself
(adminkeys:manage).
Scopes: trace and fleet content, agent key reads (keys:secret), sensitive settings, SSO, developer
revocation (users:revoke), and admin-key management scopes.
So a leaked key can never mint more keys, read an agent's key back, or relax how developers authenticate.