# How OmniRoute Handles Anthropic-Compatible Provider Authentication

> Learn how OmniRoute manages Anthropic-compatible provider authentication. Discover automatic API key injection and header management for seamless integration.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-22

---

**OmniRoute handles Anthropic-compatible provider authentication by detecting providers with the `anthropic-compatible-` prefix and injecting an `x-api-key` header built from the provider's API key or access token, while omitting standard Bearer tokens and automatically managing version and beta headers.**

OmniRoute is an open-source routing layer for LLM providers that implements specialized authentication logic for Anthropic-compatible endpoints. Unlike standard OAuth flows, these providers require specific header-based authentication that conforms to the official Anthropic API specification. This article examines the source code implementation to explain how OmniRoute constructs these authentication headers and manages provider credentials.

## Provider Detection in DefaultExecutor

The authentication flow begins with provider identification in the `DefaultExecutor` class. OmniRoute checks whether the provider ID starts with the specific prefix `anthropic-compatible-` to activate specialized handling:

```typescript
if (this.provider?.startsWith?.("anthropic-compatible-")) {
    // …special handling for Anthropic‑compatible nodes
}

```

*Source:* [[`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts), lines 129‑133](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/executors/default.ts#L129-L133)

This guard clause ensures that all subsequent header construction follows Anthropic's specific authentication contract rather than standard OpenAI-compatible Bearer token flows.

## Constructing the x-api-key Header

Once detected as Anthropic-compatible, the `DefaultExecutor.buildHeaders()` method constructs the authentication headers. The canonical header for Anthropic APIs is `x-api-key`, populated from the effective API key or falling back to the credentials' access token:

```typescript
if (effectiveKey) {
    // “x‑api‑key” is the canonical header the Anthropic API expects
    headers["x-api-key"] = effectiveKey;
}

```

If no `effectiveKey` is available, the system uses the `accessToken` as a fallback:

```typescript
headers["x-api-key"] = effectiveKey || credentials.accessToken;

```

*Source:* [[`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts), lines 371‑384](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/executors/default.ts#L371-L384)

Critically, **Bearer tokens are excluded** from Anthropic-compatible requests unless explicitly required by a specific sub-type (such as `anthropic-compatible-cc-`). This preserves the official Anthropic request format that expects the `x-api-key` header exclusively.

## Optional API Key Support

Certain Anthropic-compatible connections can operate without an API key. This policy is governed by the `providerAllowsOptionalApiKey()` helper function defined in the shared constants:

```typescript
export function providerAllowsOptionalApiKey(providerId: unknown): boolean {
    // Set of provider IDs that may omit an API key
    const optionalSet = new Set([
        "anthropic-compatible-chat-test",
        // …other test/mock IDs
    ]);
    return optionalSet.has(String(providerId));
}

```

*Source:* [[`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts), lines 190‑197](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/src/shared/constants/providers.ts#L190-L197)

The validation layer in [`src/lib/providers/validation.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/providers/validation.ts) imports this helper to determine whether a missing key should trigger a validation error. This enables test and mock providers to function without credentials while maintaining strict requirements for production connections.

## Anthropic Version and Beta Header Management

Beyond authentication, OmniRoute automatically injects required Anthropic-specific headers. The constants and normalization utilities reside in [`anthropicHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/anthropicHeaders.ts):

```typescript
export const ANTHROPIC_VERSION_HEADER = "2023-06-01";

export const ANTHROPIC_BETA_BASE = Object.freeze([
    "claude-code-20250219",
    "oauth-2025-04-20",
    // …additional beta flags
]);

export const ANTHROPIC_BETA_FULL = ANTHROPIC_BETA_BASE.join(",");

```

*Source:* [[`open-sse/config/anthropicHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/anthropicHeaders.ts), lines 1‑30](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/config/anthropicHeaders.ts#L1-L30)

The `DefaultExecutor` imports `mergeClientAnthropicBeta` and `normalizeAnthropicHeaderVariants` to:

- Add the fixed `anthropic-version` header (currently `2023-06-01`)
- Merge client-requested beta flags that are allowed in `FORWARDABLE_CLIENT_BETAS`
- Deduplicate case-variant header names to prevent the `v, v` bug

*Source:* [[`open-sse/config/anthropicHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/anthropicHeaders.ts), lines 91‑103](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/config/anthropicHeaders.ts#L91-L103)

## Practical Implementation Example

Below is a minimal implementation showing how OmniRoute assembles an Anthropic-compatible request:

```typescript
import { DefaultExecutor } from "./open-sse/executors/default.ts";

// 1️⃣ Provider ID that matches the Anthropic‑compatible prefix
const providerId = "anthropic-compatible-chat-1234";

// 2️⃣ Credentials (could be empty if the provider allows optional API keys)
const credentials = { apiKey: "sk-anthropic-demo", accessToken: "" };

// 3️⃣ Build the executor – it will auto‑detect the provider type
const executor = new DefaultExecutor(providerId);

// 4️⃣ Generate the headers for a streaming request
const headers = executor.buildHeaders(credentials, true /*stream*/);

// Resulting headers (relevant part)
console.log(headers);
/*
{
  "x-api-key": "sk-anthropic-demo",
  "anthropic-version": "2023-06-01",
  "anthropic-beta": "claude-code-20250219,oauth-2025-04-20"
}
*/

```

This example demonstrates that OmniRoute uses `x-api-key` instead of `Authorization: Bearer`, automatically injects the mandatory version header, and merges beta flags according to the provider configuration.

## Summary

- **Provider Detection:** OmniRoute identifies Anthropic-compatible providers by checking for the `anthropic-compatible-` prefix in `DefaultExecutor`.
- **Authentication Method:** The system sets the `x-api-key` header using the provider's API key or `accessToken`, deliberately omitting Bearer tokens to comply with Anthropic's API specification.
- **Optional Keys:** Test providers specified in `providerAllowsOptionalApiKey()` can omit API keys, while production providers require valid credentials.
- **Header Management:** Version (`2023-06-01`) and beta headers are automatically injected and normalized via [`anthropicHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/anthropicHeaders.ts) utilities.

## Frequently Asked Questions

### What authentication header does OmniRoute use for Anthropic-compatible providers?

OmniRoute uses the `x-api-key` header for Anthropic-compatible authentication. This is set explicitly in `DefaultExecutor.buildHeaders()` and differs from the standard `Authorization: Bearer` token approach used for OpenAI-compatible providers.

### Can Anthropic-compatible connections operate without an API key?

Yes, but only for specific test providers. The `providerAllowsOptionalApiKey()` function in [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) maintains a whitelist including identifiers like `anthropic-compatible-chat-test` that permit empty credentials. Production providers require a valid API key or access token.

### Where is the Anthropic API version defined in the OmniRoute source code?

The Anthropic API version is defined as `ANTHROPIC_VERSION_HEADER` in [`open-sse/config/anthropicHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/anthropicHeaders.ts), currently set to `2023-06-01`. This constant is automatically injected into every request header for Anthropic-compatible providers.

### How does OmniRoute handle beta features for Anthropic-compatible requests?

OmniRoute manages beta features through the `mergeClientAnthropicBeta` and `normalizeAnthropicHeaderVariants` functions in [`anthropicHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/anthropicHeaders.ts). These utilities merge server-side default beta flags with allowable client-provided betas, deduplicate variant header names, and inject the resulting `anthropic-beta` header into the request.