OmniRoute API Authentication Methods: Bearer Tokens, API Keys, and JWT Cookies Explained

OmniRoute supports three API authentication methods: Bearer-style API keys via the Authorization header, fallback x-api-key headers, and JWT cookies for management-only routes.

The OmniRoute routing gateway implements a flexible, header-first authentication system for its public HTTP API. Whether you're building automated integrations or accessing the management dashboard, understanding these OmniRoute API authentication methods ensures your requests are properly secured and validated.

Bearer-Style API Keys (Primary Method)

The recommended authentication approach uses Bearer tokens in the Authorization header. This standard OAuth 2.0 pattern provides clean separation between transport metadata and credentials.

In src/sse/services/auth.ts, the extractApiKey() function parses the header with case-insensitive matching and extracts the raw key:

// Request format
const response = await fetch("http://localhost:20128/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-my-secret-key",
  },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Hello" }]
  })
});

The function normalizes the token, trims whitespace, and passes it to isValidApiKey() for database verification against the SQLite key store in src/lib/db/apiKeys.ts.

x-api-key Header Fallback

When the Authorization header is absent or doesn't contain a Bearer token, OmniRoute falls back to the x-api-key header. This accommodates:

• Anthropic-based backends requiring "Anthropic-Version" headers
• Internal tooling that sends plain API keys
• Legacy client integrations

// Fallback authentication
await fetch("http://localhost:20128/v1/models", {
  headers: { "x-api-key": "sk-fallback-key" }
});

The same extractApiKey() implementation in src/sse/services/auth.ts handles this fallback automatically, also supporting the x-goog-api-key variant for Google-flavored requests.

JWT Cookie Authentication for Management Routes

Management-only routes—including the dashboard and admin API—require a signed auth_token cookie instead of API keys. The validation logic lives in src/lib/api/requireManagementAuth.ts:

// Management UI access
await fetch("http://localhost:20128/dashboard", {
  credentials: "include",
  headers: { "Cookie": "auth_token=eyJhbGci..." }
});

The extractJwtCookie() helper extracts and validates the JWT against the server's JWT_SECRET (configured via .env.example). Management routes explicitly disable URL-based token extraction by calling extractApiKey(..., { allowUrl: false }).

Optional Path-Scoped Tokens

OmniRoute supports embedding tokens directly in URLs for specific integration patterns. Enable this via the allowUrl flag:

// Token embedded in path
await fetch("http://localhost:20128/api/v1/vscode/combos/sk-path-token/execute", {
  method: "POST"
  // No Authorization header required
});

This mode is disabled by default for management routes to prevent accidental credential exposure in logs.

Authentication Flow Architecture

All methods converge through a unified pipeline:

1. Route entry — API routes import extractApiKey from src/sse/services/auth.ts
2. Extraction — Checks Authorization: Bearer, x-api-key, then path-embedded tokens
3. Validation — isValidApiKey() queries src/lib/db/apiKeys.ts for active keys
4. Context attachment — Verified keys become request.apiKey for downstream policies
5. Management override — JWT cookie validation via requireManagementAuth.ts

Security hard-rules enforced throughout: no raw secrets in logs (via buildErrorBody), strict header allowlists, and case-insensitive parsing for robust client compatibility.

Summary

• Bearer tokens — Standard Authorization: Bearer <key> header, the recommended approach
• x-api-key fallback — Plain header for specific provider requirements and legacy tools
• JWT cookies — Signed auth_token required for dashboard and admin API access
• Path tokens — Optional URL-embedded keys for specialized integrations, controllable via allowUrl

Frequently Asked Questions

Does OmniRoute support OAuth 2.0 or OIDC for API authentication?

No. According to the OmniRoute source code, authentication is limited to static API keys and JWT cookies. There is no OAuth 2.0 authorization server or OpenID Connect flow implemented. The "Bearer" reference in headers indicates token format only, not full OAuth protocol support.

Can I use both Authorization and x-api-key headers in the same request?

Technically yes, but the Authorization header takes precedence. In src/sse/services/auth.ts, extractApiKey() checks Authorization first and only falls back to x-api-key if no valid Bearer token is found. Redundant headers do not provide additional security benefits.

How are API keys stored and validated?

Keys are persisted in SQLite via src/lib/db/apiKeys.ts. The isValidApiKey() function performs existence and active-status checks. The system does not hash keys in memory during extraction—validation happens against the database with each request, enabling immediate revocation.

What happens if authentication fails?

All authentication failures return 401 Unauthorized with sanitized error bodies. The buildErrorBody utility ensures no raw secrets leak in error responses. Management routes that fail JWT validation trigger the same response path, though cookie-specific errors may include additional context for browser-based sessions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}