Authorization: Bearer <admin-key>
Browser authentication: named administrator session cookie plus the per-login CSRF token automatically supplied by the packaged console on mutations. The token is bound to that session and static or stale values are rejected. Admin bearer keys require both role: admin and matching endpoint scope and retain full automation access. Most data APIs require Postgres persistence.
Organization scope is enforced by the API, not the browser. Organization roles must have exactly one
org_id; omitted key ownership is bound to that organization, supplying another org_id returns 403 tenant_scope_violation, and identifier lookups include the actor’s organization predicate. System roles reject org_id.
Only a system_admin can create, update, rotate, or revoke role: admin bearer keys; organization and system operator key-management permission cannot be used for privilege escalation. The legacy values admin, operator, and viewer remain accepted as aliases for system_admin, system_operator, and org_viewer.
Console administrators
The first administrator is deployment-owned. A password must be 12-128 characters. Creation accepts
role; every org_* role requires org_id, while every system_* role rejects it. The last active system_admin (including legacy admin records) cannot be disabled.
When OIDC is configured, the console offers the deployment provider label. Initiation is distributed-throttled before provider discovery or database state creation. The gateway verifies discovery issuer equality, HTTPS endpoints, PKCE S256, one-time state, signature and approved algorithm, issuer, audience, expiry, nonce, and authorized party. Provider subjects are mapped explicitly to gateway usernames/roles/tenant scopes; token group or role claims cannot grant access. Retain a restricted audited password identity for break-glass recovery.
When Platform handoff is configured, the Platform backend—not the browser—selects the current membership and signs its immutable subject, organization, current role, and high-resolution authority time. The token expires within five minutes at most, is consumed once through Postgres, and is submitted by body/form rather than a URL. Signed logout actions include the original logout cutoff, so delayed retries preserve sessions created by later logins without relying on clocks from different services. Persisted global and organization cutoffs also reject handoffs minted before logout but exchanged after delivery. One Platform subject may hold multiple independent organization principals. Platform admin, editor, and viewer map only to org_admin, org_operator, and org_viewer; a handoff can never create system authority.
Audit events
Each state-changing route records an
attempt before mutation and an outcome with actor, authentication type, role, tenant scope, request/instance IDs, action, target, result, status, and allowlisted redacted metadata. Filters are actor_subject, action, outcome, org_id, and limit=1..500. Only system administrators can read this endpoint.
When Postgres audit preflight is unavailable, administrative mutations fail closed with 503 admin_audit_unavailable. If only the post-action outcome write fails, the response includes X-Gateway-Audit-Status: failed and readiness remains failed until a later audit write succeeds; verify the target state before considering any retry.
Runtime and configuration
Changes to persistence, shared state, alert worker, signals, reconciliation, or catalog-propagation configuration require restart. In a multi-process deployment, general configuration reload affects only the process receiving the request; catalog generations propagate separately.
Signals and weekly digests
Signals require Postgres and use request metadata only. The initial rules cover sustained server-error rate, rate-limit rate, missing billable usage, and p95 latency with a previous-window regression guard. Minimum sample counts plus consecutive breach and recovery windows suppress one-off noise. Firing, reminder, resolved, and completed-week digest notifications use the configured durable Slack or Google Chat outbox. The API does not expose the webhook URL.
Model catalog
For system roles, every mutation includes the latest non-negative
revision; stale updates return 409 model_catalog_conflict. The gateway validates the entire routing graph, requires reviewed pricing for enabled API-managed models, builds and readiness-checks a new engine, persists the revision, and then atomically swaps the runtime. Deployment-owned global provider credentials cannot be created through these endpoints.
An org_admin sees and mutates only its organization’s BYOK models and weighted aliases through the same routes. BYOK credential documents are encrypted at rest and returned only as masked previews. The deployment’s byok.custom_api_base_policy can disable custom endpoints, require operator-approved hosts (the default), or accept public HTTPS hostnames. Every mode rejects IP-literal custom endpoints; configured endpoints must use HTTPS, contain no URL credentials/query/fragment, and resolve only to public addresses when created or updated. Production deployments also enforce outbound network policy against private and metadata destinations. Organization operators and viewers have read-only catalog access. An aliased model cannot be deleted until its aliases are changed or removed.
At startup, an unusable stored catalog is reported as source: database_pending with activation_status: degraded. The process keeps the deployment model baseline active for diagnosis; /ready reports component degradation but remains 200 while that safe runtime is serving. Use the returned pending revision to repair the graph or call the reset endpoint. If schema_version is newer than supported_schema_version, the replica returns model_catalog_schema_unsupported and rejects catalog mutations or reload with 409; upgrade it or intentionally reset the pending revision.
With Postgres, each mutation and reset advances a monotonic generation. Replicas automatically poll and acknowledge it as active, applying, or failed; stale acknowledgements are marked separately. Every process needs a unique LLM_GATEWAY_INSTANCE_ID. A replica that is behind or cannot activate fails model_catalog_ready until it catches up or the catalog is repaired, without discarding its last safe runtime.
API keys
Creating a key with RPM or TPM limits requires Redis shared state unless the deployment explicitly acknowledges one-process memory enforcement with
shared_state.allow_process_local_throttling: true. Otherwise POST /admin/keys returns 409 distributed_rate_limits_required and does not persist the key.
Admin-created keys require org_id. Rotation accepts {"overlap_seconds": 300} with a range of 0-86,400 seconds and returns the new raw token once. A zero overlap invalidates the previous token immediately; revocation invalidates the current and overlapping token. See API keys for the full workflow.
Usage
Common filters are
start_at, end_at, api_key_id, org_id, app_id, environment, model, provider, and status_code.
Budgets
Manual reconciliation returns 409 while a reservation is still inside its active execution window.
Reservation rows include automatic reconciliation attempt, retry, error, and soft-quarantine fields. A manual reconcile remains available for a stale quarantined row after its underlying data is repaired; it does not wait for the automatic retry timestamp.
Organization limits
Aggregate throttling ceilings apply across every key in an organization and are enforced before per-key limits. Only asystem_admin can read or change these ceilings; tenant roles cannot raise their own limits.
Requests that exceed an organization’s request or token rate return
429 org_rate_limit_exceeded with a Retry-After header; requests over the organization’s concurrent-request limit return 429 concurrency_limit_exceeded. Organization rate and concurrency limits require Redis shared state unless the deployment explicitly acknowledges one-process memory enforcement.
Operator UI
Self-managed builds include/admin/ui for models, aliases, application keys, console administrators, usage, cost, budgets, alerts, and reservations. Keep it on the private operator origin.