/omni-auth

name: omni-auth
description: Manage API key authentication and session tokens. Start here to authenticate requests via Bearer token, obtain session cookies, and configure login requirements for the OmniRoute API.

<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

Overview

Manage API key authentication and session tokens. Start here to authenticate requests via Bearer token, obtain session cookies, and configure login requirements for the OmniRoute API.

Authentication

Remote API requests use a Bearer credential. Dashboard login is different: `POST /api/auth/login` accepts a management password and returns an `auth_token` session cookie.

Endpoints

POST /api/auth/login

Authenticate user

curl -X POST http://localhost:20128/api/auth/login \
  -H "Content-Type: application/json" \
  -c cookie.jar \
  -d '{"password":"<management-password>"}'

POST /api/auth/mfa/verify

Complete a two-factor sign-in

Login step 2 (public). Trades the MFA-pending cookie set by `/api/auth/login` plus a TOTP or recovery code for the dashboard session cookie. Shares the login brute-force lockout; a TOTP step and a recovery code are each accepted once.

CSRF_TOKEN=$(curl -s http://localhost:20128/api/auth/csrf -b cookie.jar | jq -r .token)
curl -X POST http://localhost:20128/api/auth/mfa/verify \
  -b cookie.jar \
  -H "x-omniroute-csrf: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/auth/mfa/status

Two-factor authentication status

curl http://localhost:20128/api/auth/mfa/status \
  -b cookie.jar

POST /api/auth/mfa/setup

Start two-factor enrollment

Re-authenticates with the current password and returns a candidate TOTP secret, its `otpauth://` URI and a QR code (PNG data URI). Nothing is persisted.

CSRF_TOKEN=$(curl -s http://localhost:20128/api/auth/csrf -b cookie.jar | jq -r .token)
curl -X POST http://localhost:20128/api/auth/mfa/setup \
  -b cookie.jar \
  -H "x-omniroute-csrf: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/auth/mfa/enable

Finish two-factor enrollment

Persists the secret (encrypted at rest) once the current password and a code generated from it both verify. Returns ten single-use recovery codes, shown once.

CSRF_TOKEN=$(curl -s http://localhost:20128/api/auth/csrf -b cookie.jar | jq -r .token)
curl -X POST http://localhost:20128/api/auth/mfa/enable \
  -b cookie.jar \
  -H "x-omniroute-csrf: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/auth/mfa/disable

Turn two-factor authentication off

Requires the current password and a live TOTP or recovery code. While `OMNIROUTE_DISABLE_MFA=true` is set, a request from the host itself (loopback peer and loopback `Host`) may omit `code` to remove a factor that can no longer be verified; the session and password are still required.

CSRF_TOKEN=$(curl -s http://localhost:20128/api/auth/csrf -b cookie.jar | jq -r .token)
curl -X POST http://localhost:20128/api/auth/mfa/disable \
  -b cookie.jar \
  -H "x-omniroute-csrf: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/auth/logout

Log out

CSRF_TOKEN=$(curl -s http://localhost:20128/api/auth/csrf -b cookie.jar | jq -r .token)
curl -X POST http://localhost:20128/api/auth/logout \
  -b cookie.jar \
  -H "x-omniroute-csrf: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/auth/oidc/login

Start OIDC login for the dashboard admin gate

Builds an authorization URL from the configured OIDC issuer/client (discovered via `{issuer}/.well-known/openid-configuration`, falling back to `{issuer}/authorize`), sets a short-lived `oidc_state` cookie, and redirects the browser. Password login remains available as a fallback while OIDC is enabled.

curl http://localhost:20128/api/auth/oidc/login \
  -b cookie.jar

GET /api/auth/oidc/callback

Complete OIDC login for the dashboard admin gate

Validates the `state` cookie, exchanges the authorization `code` for tokens, verifies the ID token against the issuer's JWKS (audience = client id), and requires at least one dashboard admission policy: `oidcAllowedSubjects` (matching `sub` or verified `email`) or `oidcAdmissionClaim` (matching a configured array claim in the verified ID token). When both are present, both must match. Without either policy the callback returns `not_configured`. On success it mints the same 30-day `auth_token` dashboard-session JWT used by password login and redirects to `/dashboard`.

curl http://localhost:20128/api/auth/oidc/callback \
  -b cookie.jar

GET /api/auth/csrf

GET auth › csrf

curl http://localhost:20128/api/auth/csrf \
  -b cookie.jar

GET /api/auth/status

GET auth › status

curl http://localhost:20128/api/auth/status \
  -b cookie.jar

Payloads

See the full OpenAPI specification at `GET /api/openapi/spec` or `docs/openapi.yaml` for detailed request/response schemas.

<!-- skill:custom-start --> <!-- Migrated from skills/omniroute/SKILL.md (preserved curated content) -->

OmniRoute

Local/remote AI gateway exposing OpenAI-compatible REST. One key, 393 providers, auto-fallback, RTK token saver, MCP server, A2A agents.

Setup

export OMNIROUTE_URL="http://localhost:20128"      # or VPS / tunnel URL
export OMNIROUTE_KEY="sk-..."                       # from Dashboard → API Keys

All requests: `${OMNIROUTE_URL}/v1/...` with `Authorization: Bearer ${OMNIROUTE_KEY}`.

Verify: `curl $OMNIROUTE_URL/api/health` → `{"ok":true}`

Discover models

curl $OMNIROUTE_URL/v1/models                  # chat/LLM (default)
curl $OMNIROUTE_URL/v1/models/image            # image-gen
curl $OMNIROUTE_URL/v1/models/tts              # text-to-speech
curl $OMNIROUTE_URL/v1/models/embedding        # embeddings
curl $OMNIROUTE_URL/v1/models/web