Security APIs #

API key management for the data plane. Only meaningful with security.auth_enabled: true in pizza.yml — with auth off, the mint and revoke endpoints refuse to act rather than minting keys into an open API, and the list endpoints report the inert state instead.

Minted and revoked keys replicate through the catalog Raft (AddSecurityKey / RemoveSecurityKey), so they survive restarts and reach every node. Config-declared keys remain a second, file-backed source, and revocation tombstones keep revoked config/bootstrap keys from resurrecting on reboot.

See Security for the configuration side: enabling auth, the bootstrap key, statically declared keys, and the role model.

Who Am I #

The console’s auth probe. Reports whether auth is on and, for the caller’s key, the resolved identity. Under auth an absent or invalid key never reaches the handler (the middleware answers 401); with auth off it answers {"auth_enabled": false} so clients can skip login entirely.

Request #

GET /_security/whoami

Response #

{
  "auth_enabled": true,
  "identity": { "tenant": "", "user": "", "role": "platform_admin" }
}

Mint an API key #

Creates a new API key. The raw key is returned exactly once, at mint time — it is never stored server-side in the clear.

Only roles that may manage keys (platform_admin, namespace_admin within its own namespace) can mint. namespace_admin may only mint plain data roles (read_write, read_only) inside its own namespace.

Request #

POST /_security/key
{
  "tenant": "my-tenant",
  "user": "ci-runner",
  "role": "read_write",
  "name": "nightly-exporter",
  "expires_in_secs": 86400
}

Request body #

• tenant
  (Required for data-plane roles, string) The owning tenant; normalized away for ops roles (operator, monitor).
• user
  (Required, string) The user the key identifies.
• role
  (Required, string) One of platform_admin, operator, monitor, namespace_admin, read_write, read_only.
• name
  (Optional, string, max 128 bytes) A label shown in listings.
• expires_in_secs
  (Optional, integer) Lifetime in seconds, clamped to 365 days. Absent means no expiry.

Response #

{
  "key": "pz_...",
  "id": "...",
  "name": "nightly-exporter",
  "tenant": "my-tenant",
  "user": "ci-runner",
  "role": "read_write",
  "created_at": 1700000000,
  "expires_at": 1700086400
}

List API keys #

Returns the key catalog (ids, tenants, users, roles — never the key material). namespace_admin sees only its own namespace’s keys.

Request #

GET /_security/keys
GET /_security/key

Revoke an API key #

Revokes the key with the given id. Revocations replicate through the catalog so the key cannot resurrect on reboot; a revoked bootstrap or config-declared key stays revoked the same way.

Request #

DELETE /_security/key/<id>

Path Parameters #

• id
  (Required, string) The key id returned at mint time or shown in the listing.