Skip to main content
Agent skill

Omni Auth

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.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Omni Auth when an AI agent needs a reusable SKILL.md workflow for this job: 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.

When not to use it

Skip Omni Auth when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/omni-auth
# Save SKILL.md to ~/.claude/skills/omni-auth/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/omni-auth/SKILL.md. For a shared project, commit the folder at .claude/skills/omni-auth/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Omni Auth skill for this task: Use Omni Auth when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • chatgptinferred

    The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

<!-- 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/mfa/verify

Complete a two-factor sign-in

Login step 2 (public). Trades the MFA-pending cookie set by `/api/auth/login` plus a TOTP or recovery code for the dashboard session cookie. Shares the login brute-force lockout; a TOTP step and a recovery code are each accepted once.

```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/mfa/verify \ -b cookie.jar \ -H "x-omniroute-csrf: $CSRF_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### GET /api/auth/mfa/status

Two-factor authentication status

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

### POST /api/auth/mfa/setup

Start two-factor enrollment

Re-authenticates with the current password and returns a candidate TOTP secret, its `otpauth://` URI and a QR code (PNG data URI). Nothing is persisted.

```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/mfa/setup \ -b cookie.jar \ -H "x-omniroute-csrf: $CSRF_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### POST /api/auth/mfa/enable

Finish two-factor enrollment

Persists the secret (encrypted at rest) once the current password and a code generated from it both verify. Returns ten single-use recovery codes, shown once.

```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/mfa/enable \ -b cookie.jar \ -H "x-omniroute-csrf: $CSRF_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### POST /api/auth/mfa/disable

Turn two-factor authentication off

Requires the current password and a live TOTP or recovery code. While `OMNIROUTE_DISABLE_MFA=true` is set, a request from the host itself (loopback peer and loopback `Host`) may omit `code` to remove a factor that can no longer be verified; the session and password are still required.

```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/mfa/disable \ -b cookie.jar \ -H "x-omniroute-csrf: $CSRF_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### 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 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`.

```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, hundreds of 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` → `{"status":"ok","timestamp":"..."}`

## Discover models

```bash curl $OMNIROUTE_URL/v1/models # chat/LLM (default) curl "$OMNIROUTE_URL/v1/models?kind=image" # image-gen curl "$OMNIROUTE_URL/v1/models?kind=audio" # text-to-speech + speech-to-text curl "$OMNIROUTE_URL/v1/models?kind=embedding" # embeddings curl $OMNIROUTE_URL/v1/search # web search providers ```

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/cheaper-inference/OmniRoute/main/skills/omni-inference/SKILL.md | | Image generation | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-inference/SKILL.md | | Text-to-speech | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-inference/SKILL.md | | Speech-to-text | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-inference/SKILL.md | | Embeddings | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-inference/SKILL.md | | Web search | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-inference/SKILL.md | | Web fetch | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-inference/SKILL.md | | MCP server | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-mcp/SKILL.md | | A2A protocol | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-agents-a2a/SKILL.md | | Routing & combos | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-combos-routing/SKILL.md | | Token compression | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-compression/SKILL.md | | Monitoring & health | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/omni-resilience/SKILL.md |

## CLI skills (omniroute binary)

| Capability | Raw URL | | -------------------------------------- | --------------------------------------------------------------------------------------------- | | CLI entry point | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/cli-serve/SKILL.md | | CLI admin & lifecycle | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/cli-serve/SKILL.md | | CLI providers & keys | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/cli-providers/SKILL.md | | CLI cloud agents (`omniroute cloud …`) | https://raw.githubusercontent.com/cheaper-inference/OmniRoute/main/skills/cli-backup-sync/SKILL.md | | CLI evals & benchmarks | https://raw.githubusercontent.com/cheaper-inference/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 (every routing strategy): 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 -->

Intended uses

  • Use Omni Auth when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.