Authentication

Every API request authenticates with a bearer token in the Authorization header. This mirrors OpenAI exactly, so an existing client authenticates against Zumik without code changes.

-H "Authorization: Bearer zk_live_..."

Create keys in the console. Inference also requires a positive prepaid credit balance; with an empty balance, inference endpoints return 402 with code credits_required (see errors).

Key format

Keys are prefixed so they are easy to recognize and easy to scan for in source control.

A key is shown in full exactly once, at creation. Zumik stores only a hash of the key plus a masked display form (for example zk_live_4ab2…cdef), so a leaked database never reveals a usable key. If a key leaks, revoke it and mint a new one; deleting it from your code is not enough.

Console sessions

The dashboard authenticates with a login session cookie instead of a pasted key, so the console can read your project's data without you copying a secret into the browser. Programmatic clients always use a bearer key. The cookie path is internal to the console and is not part of the public API contract.

Per-key budgets

Each API key can carry its own spending limit, independent of the project's overall budget. This lets you hand a scoped key to a job, a teammate, or an environment and cap what it can spend.

• Set a per-key limit in the console or via the key-management API.
• A key that reaches its limit is refused with 429 and code quota_exceeded, with a message pointing at the per-key budget.
• The per-key cap is a post-paid soft limit: under concurrent in-flight requests on one key it can overshoot by roughly the cost of the requests already in flight, because the exact cost is known only after the provider call. The project credit balance is the hard money guarantee and is charged atomically.

The project-wide budget is enforced first. When a project is out of budget under pause mode, requests are refused with 429 / quota_exceeded before any provider call runs. See rate limits for the throughput limits that sit alongside budgets.

Scopes

Keys carry scopes. Inference and most project operations work with a default-scoped key. Platform-level mutations (for example reshaping model-alias routing for the whole project) require the admin scope; a key without it is refused with 403 and code insufficient_scope.

The 401 shape

A missing, malformed, or unknown bearer token returns the standard OpenAI-compatible error envelope with HTTP 401:

{
  "error": {
    "message": "Missing or invalid API key.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

This is the same envelope OpenAI returns, so existing SDK error handling treats it identically. See errors for the complete code table.

Next