omni-auth — Claude Code skill: OmniRoute authentication

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