--- 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. --- ## 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 ```bash curl -X POST https://localhost:20128/api/auth/login \ -H "Content-Type: application/json" \ -c cookie.jar \ -d '{"password":""}' ``` ### POST /api/auth/logout Log out ```bash CSRF_TOKEN=$(curl -s https://localhost:20128/api/auth/csrf -b cookie.jar | jq -r .token) curl -X POST https://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. ```bash curl https://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 — if `oidcAllowedSubjects` is configured — checks the token's `sub`/`email` against that allowlist. On success it mints the same 30-day `auth_token` dashboard-session JWT used by password login and redirects to `/dashboard`. ```bash curl https://localhost:20128/api/auth/oidc/callback \ -b cookie.jar ``` ### GET /api/auth/csrf GET auth › csrf ```bash curl https://localhost:20128/api/auth/csrf \ -b cookie.jar ``` ### GET /api/auth/status GET auth › status ```bash curl https://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, 327 providers, auto-fallback, RTK token saver, MCP server, A2A agents. ## Setup ```bash 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 ```bash 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 | Capability | Raw URL | | ---------------------- | ------------------------------------------------------------------------------------------------- | | Chat / code-gen | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md | | Image generation | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md | | Text-to-speech | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md | | Speech-to-text | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md | | Embeddings | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md | | Web search | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md | | Web fetch | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-inference/SKILL.md | | MCP server (110 tools) | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-mcp/SKILL.md | | A2A protocol | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-agents-a2a/SKILL.md | | Routing & combos | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-combos-routing/SKILL.md | | Token compression | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-compression/SKILL.md | | Monitoring & health | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-resilience/SKILL.md | ## CLI skills (omniroute binary) | Capability | Raw URL | | -------------------------------------- | --------------------------------------------------------------------------------------------- | | CLI entry point | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-serve/SKILL.md | | CLI admin & lifecycle | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-serve/SKILL.md | | CLI providers & keys | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-providers/SKILL.md | | CLI cloud agents (`omniroute cloud …`) | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-backup-sync/SKILL.md | | CLI evals & benchmarks | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-eval/SKILL.md | ## Errors - `401` → set/refresh `OMNIROUTE_KEY` (Dashboard → API Keys) - `400 Invalid model format` → check `model` exists in `/v1/models/` - `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