Authentication

Zumik has two authentication planes that never mix.

• API keys authenticate programmatic calls to /v1 and /v2. A key is a bearer token in the Authorization header.
• Console sessions authenticate a human in the dashboard. A person signs in with email and password or with Google or GitHub, gets an httpOnly session cookie, and from there manages projects, billing, and keys.

API keys

A key looks like zk_live_ followed by 32 url-safe characters. It belongs to one project, and every call made with it operates inside that project's tenant boundary.

The full key is shown exactly once, at creation. Zumik stores only a SHA-256 hash of it for lookup, plus a masked form (zk_live_4ab2…cdef) for display. A leaked database snapshot cannot be replayed as a live key, because the raw value is never persisted.

Bearer auth

Send the key as a bearer token. A missing or unknown key returns the standard 401 error body, matching OpenAI exactly so existing client error handling works unchanged.

curl https://api.zumik.ai/v1/responses \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"auto.balanced","input":"Hello"}'

Scopes

Each key carries one or more scopes. The console mints inference and read keys; admin keys reshape platform routing (such as model aliases) and are managed deliberately rather than from the self-service UI.

An inference-only key cannot reshape routing for everyone else, which keeps a shared key from changing behavior for the whole project.

Per-key budgets

A single key can carry its own spending limit, independent of the project cap. This stops one team member's key from draining a shared budget. Set it with POST /v2/api-keys/{key_id}/budget, in whole dollars.

curl -X POST https://api.zumik.ai/v2/api-keys/key_01jy.../budget \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"limit_usd": 25.0}'

A key that exhausts its own limit returns 429 quota_exceeded, even when the project cap still has room. Pass null to clear the per-key limit. See credits and budgets for how this composes with the project budget.

Rotating and revoking keys

Rotation is mint-then-revoke: create the replacement key, deploy it, then revoke the old one. There is no in-place secret swap, by design.

# Revoke a key, it stops authenticating immediately
curl -X DELETE https://api.zumik.ai/v2/api-keys/key_01jy... \
  -H "Authorization: Bearer zk_live_..."
# => { "id": "key_01jy...", "object": "api_key.revoked", "revoked": true }

Revocation removes the stored hash, so the key fails auth on the very next request. Both creation and revocation are written to the project audit log.

Console sessions

The dashboard authenticates with a session cookie, not a pasted key, so the full console reads its project data with your login session. Sessions are random opaque tokens; only a SHA-256 hash is stored, the raw token lives in the cookie. The cookie is HttpOnly, Secure, and SameSite=Lax, which is the CSRF defense for the cookie-authed console routes.

Passwords are hashed with Argon2id. A login is rate-limited per email (eight failures in fifteen minutes locks the account for the window), which blunts credential stuffing better than a per-IP limit. A password reset revokes every other session for that user, so a stolen session cannot outlive the reset.

Sessions last 30 days and refresh on use. Use log out everywhere to revoke every session at once after losing a device.