Security #

Pizza ships an API-key based authentication and role model for the data plane and management APIs. It is off by default; the shipped pizza.yml enables it.

Enabling authentication #

security:
  auth_enabled: true
  # no bootstrap_key here — see below

With auth enabled, every data-plane and management request must carry a valid API key — Authorization: Bearer <key> or X-Api-Key: <key>. Unauthenticated requests are answered with 401 and a deliberately generic body. Anonymous operational-plane reads (console assets, readiness probes) stay open; mutating /_cluster and /_node management requires a key once auth is on.

The bootstrap key #

bootstrap_key is a one-shot platform_admin key minted at startup. The shipped pizza.yml declares none, and no secret needs to be written into any file: boot config loading checks the PIZZA_BOOTSTRAP_KEY environment variable first, so exporting it pins a stable key — that is how CI gets one. With nothing set and auth_enabled: true, the node generates a random login token and prints it to the terminal at startup. Set the config value to "" to opt out of the bootstrap key entirely (an explicit opt-out is never overridden by the environment). It exists to bootstrap the first admin; prefer minted or config-declared keys for steady state.

Statically declared keys #

Keys can be declared in the config file as SHA-256 hex hashes, surviving restarts by living in pizza.yml:

security:
  auth_enabled: true
  keys:
    - id: ci-runner
      hash: "<lowercase hex sha256 of the raw key>"
      tenant: my-tenant
      user: ci
      role: read_write

Generate a hash with e.g. printf %s 'pz_<key>' | shasum -a 256.

Roles #

Role	Scope
`platform_admin`	Full platform administration, including key management.
`operator`	Ops-plane administration (cluster/node management), tenant-less.
`monitor`	Read-only ops plane (monitoring), tenant-less.
`namespace_admin`	Administers one namespace (tenant): mints only `read_write`/`read_only` keys inside its own namespace.
`read_write`	Full data-plane access to the key’s tenant/namespace.
`read_only`	Read-only data-plane access to the key’s tenant/namespace.

Managing keys at runtime #

Keys minted through the API replicate through the catalog Raft — they survive restarts and reach every node; revocations carry tombstones so revoked config/bootstrap keys cannot resurrect on reboot. The examples below assume the node was started with PIZZA_BOOTSTRAP_KEY=pz_bootstrap_key:

# mint a key (the raw key is returned exactly once)
curl -X POST http://127.0.0.1:28000/_security/key \
  -H 'Authorization: Bearer pz_bootstrap_key' \
  -H 'Content-Type: application/json' \
  -d '{"tenant": "my-tenant", "user": "ci", "role": "read_write"}'

# list keys (ids/tenants/roles — never key material)
curl http://127.0.0.1:28000/_security/keys \
  -H 'Authorization: Bearer pz_bootstrap_key'

# revoke
curl -X DELETE http://127.0.0.1:28000/_security/key/<id> \
  -H 'Authorization: Bearer pz_bootstrap_key'

The full API reference — including GET /_security/whoami, expiry handling and the namespace-admin fencing rules — lives in Security APIs. The built-in web console (/_ui/) has a login flow and a Security page built on these endpoints.