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/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.

OmniRoute

Local/remote AI gateway exposing OpenAI-compatible REST. One key, 380 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              # web search + fetch
curl $OMNIROUTE_URL/v1/models/stt              # speech-to-text

Use data[].id as model field in requests. Combos appear with owned_by:"combo".

Capability skills

CLI skills (omniroute binary)

Errors

• 401 → set/refresh OMNIROUTE_KEY (Dashboard → API Keys)
• 400 Invalid model format → check model exists in /v1/models/<kind>
• 503 Provider circuit open → upstream provider down; retry after Retry-After seconds
• 429 → rate limited; honor Retry-After

Differentiators vs OpenAI direct

• Auto-fallback combos (19 strategies): never stop coding even if a provider rate-limits
• RTK token saver: tool_result compressed via 47 specialized filters (git-diff, test-jest, terraform-plan, docker-logs…) — 20-40% token reduction
• Caveman mode: optional terse system prompt injection (LITE/FULL/ULTRA) — 15-25% completion reduction
• MCP + A2A servers built-in (this is the only AI router that exposes both protocols)
• Memory with FTS5 + Qdrant for persistent agent context
• Guardrails for PII masking, prompt injection detection, vision policies