Management Authentication

OmniRoute has four credential families that can authorize management routes. They are not interchangeable. Inference API keys (sk-…) do not manage the server unless they were explicitly granted manage or admin scope.

Canonical implementation: src/lib/api/requireManagementAuth.ts.

oma_ credentials are management/CLI credentials. They are not inference API keys.

If login/API-key auth is disabled for the server, some management routes may accept unauthenticated calls. Local-only and always-protected routes still apply their own rules. Presenting one of these credentials is therefore not universally mandatory, and possessing one is not universally sufficient without the required scope and route locality.

Related: Remote Mode (how oma_live_… is minted for a remote CLI).

Scope matrices

These two scope vocabularies are different. Do not mix them.

Access Token scopes (oma_live_…)

A token with read cannot call a write route. Runtime message shape: Access token scope '<have>' is insufficient; '<need>' required.

API-key management scopes

Enable manage on the key in the API Keys / API Manager UI. Do not reuse a chat client key for automation unless you deliberately granted that scope.

How to create and revoke

Dashboard JWT session

1. Open /login, sign in with the management password (INITIAL_PASSWORD on first boot).
2. Cookie auth_token is HttpOnly. Browser dashboard uses it automatically.
3. Log out via /api/auth/logout. There is no long-lived secret to copy.

CLI machine-id token

1. Run omniroute on the same host as the server (loopback).
2. The CLI bootstraps a machine-id token under ~/.omniroute/ (chmod 600).
3. This does not work from another machine. Use an Access Token for remote CLI.

Scoped Access Token (oma_live_…)

1. Dashboard: Settings → Access Tokens → create (name + scope). The secret is shown once.
2. Or CLI: omniroute connect <host> (password → token). See Remote Mode.
3. Header: Authorization: Bearer oma_live_…
4. Revoke from the same Access Tokens page (or delete the CLI context).
5. Server stores only a hash. Treat the plaintext like a password.

Manage-scoped API key

1. Dashboard: API Manager / API Keys → create or edit a key → enable manage (or admin).
2. Header: Authorization: Bearer sk-… (the key's actual prefix).
3. Revoke or strip manage in the same UI.
4. Least privilege for automation that is not the CLI: prefer a read Access Token for GET-only jobs; use manage on an API key only when the caller must also speak /v1 and management.

Header format

Authorization: Bearer oma_live_<secret>
Authorization: Bearer sk-<secret>
Cookie: auth_token=<dashboard-jwt>

Do not put management credentials in the URL path or query string. Management auth is header/cookie only.

Copy-paste examples

Read-only (list providers). Use a read Access Token:

curl -sS "$OMNIROUTE_URL/api/providers" \
  -H "Authorization: Bearer oma_live_<read-token>"

Modifying (create a provider connection). Use write/admin Access Token or a manage-scoped API key:

curl -sS -X POST "$OMNIROUTE_URL/api/providers" \
  -H "Authorization: Bearer oma_live_<write-or-admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","apiKey":"<upstream-key>"}'

Inference (not management). Ordinary API key, no manage required:

curl -sS "$OMNIROUTE_URL/v1/models" \
  -H "Authorization: Bearer sk-<inference-key>"

Current runtime errors (do not echo secrets)

"Invalid management token" means the bearer was not accepted as a management credential. It does not tell you which family to mint. Use the table above: inference keys need manage scope; remote CLI needs oma_live_…; the dashboard uses the session cookie.

Recommended least-privilege choice