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

> Explore OmniRoute API authentication methods including Bearer tokens, API keys, and JWT cookies. Secure your access efficiently.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: api-reference
- Published: 2026-08-13

---

**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](https://github.com/diegosouzapw/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts), the `extractApiKey()` function parses the header with case-insensitive matching and extracts the raw key:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/api/requireManagementAuth.ts):

```typescript
// 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:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.