How OmniRoute Handles Anthropic-Compatible Provider Authentication

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:

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

Source: [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:

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:

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

Source: [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:

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, 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 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:

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, 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, 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:

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 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 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, 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. 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.

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