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 http://localhost:20128/api/auth/login \
  -H "Content-Type: application/json" \
  -c cookie.jar \
  -d '{"password":"<management-password>"}'

POST /api/auth/logout

Log out

bash

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.

bash

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 checks the token's

sub

email

against

oidcAllowedSubjects

, which must hold at least one entry (an empty list ends in

not_configured

). On success it mints the same 30-day

auth_token

dashboard-session JWT used by password login and redirects to

/dashboard

bash

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

GET /api/auth/csrf

GET auth › csrf

bash

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

GET /api/auth/status

GET auth › status

bash

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

Payloads

See the full OpenAPI specification at

GET /api/openapi/spec

docs/openapi.yaml

for detailed request/response schemas.

OmniRoute

Local/remote AI gateway exposing OpenAI-compatible REST. One key, 375 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

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

omni-auth

NPX Install

Tags

SKILL.md Content

Overview

Authentication

Endpoints

POST /api/auth/login

POST /api/auth/logout

GET /api/auth/oidc/login

GET /api/auth/oidc/callback

GET /api/auth/csrf

GET /api/auth/status

Payloads

OmniRoute

Setup

Discover models

Capability skills

CLI skills (omniroute binary)

Errors

Differentiators vs OpenAI direct