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

```bash
curl -X POST https://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 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
```

## 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, 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/omniroute-chat/SKILL.md        |
| Image generation      | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-image/SKILL.md       |
| Text-to-speech        | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-tts/SKILL.md         |
| Speech-to-text        | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-stt/SKILL.md         |
| Embeddings            | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-embeddings/SKILL.md  |
| Web search            | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-web-search/SKILL.md  |
| Web fetch             | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-web-fetch/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/omniroute-a2a/SKILL.md         |
| Routing & combos      | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-routing/SKILL.md     |
| Token compression     | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-compression/SKILL.md |
| Monitoring & health   | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-monitoring/SKILL.md  |

## CLI skills (omniroute binary)

| Capability             | Raw URL                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| CLI entry point        | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli/SKILL.md           |
| CLI admin & lifecycle  | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-admin/SKILL.md     |
| CLI providers & keys   | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-providers/SKILL.md |
| CLI cloud agents       | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-cli-cloud/SKILL.md     |
| CLI evals & benchmarks | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-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
<!-- skill:custom-end -->