Does OmniRoute Require API Keys for All Providers?

No—OmniRoute does not require API keys for all providers by default. The need for an API key is controlled by the REQUIRE_API_KEY feature flag, which is disabled by default, allowing anonymous access to free providers like qoder, opencode, and aihorde.

OmniRoute is a flexible AI model routing proxy that balances ease of use with security. Whether you're running a single-user local instance or a production deployment, understanding how API key requirements work is essential for proper configuration.

How API Key Requirements Work in OmniRoute

The REQUIRE_API_KEY feature flag determines whether incoming requests must include a valid OmniRoute API key. This flag lives in src/shared/constants/featureFlagDefinitions.ts and defaults to false:

// src/shared/constants/featureFlagDefinitions.ts (lines 17-24)
REQUIRE_API_KEY: {
  defaultValue: false,
  description: 'Require API key for all requests',
  type: 'boolean',
},

When this flag is false, the server accepts anonymous traffic for providers that don't need credentials. When set to true, every request must include a valid API key in the Authorization header.

The Runtime Policy Check

The enforcement logic resides in src/server/authz/policies/clientApi.ts (lines 83-92). Here's how the policy evaluates requests:

// src/server/authz/policies/clientApi.ts
// When REQUIRE_API_KEY is false, bypass authentication entirely
if (!isFeatureFlagEnabled('REQUIRE_API_KEY')) {
  return { allowed: true }; // Anonymous access permitted
}
// Otherwise, validate the Bearer token against OMNIROUTE_API_KEY

The client-side helper in src/shared/utils/clientApiRouteAuth.ts (lines 11-17) documents the expected header format when keys are required:

// src/shared/utils/clientApiRouteAuth.ts
const apiKey = req.headers.authorization?.replace('Bearer ', '');
if (!apiKey && isFeatureFlagEnabled('REQUIRE_API_KEY')) {
  throw new UnauthorizedError('API key required');
}

Free Providers That Need No API Key

OmniRoute includes built-in "no-auth" providers that work without any credentials. These are enumerated in src/shared/constants/providers.ts under FREE_APIKEY_PROVIDER_IDS (lines 23-38):

Provider ID	Description
qoder	Local code generation model
opencode	Open code completion provider
dahl	Lightweight inference endpoint
auggie	Augmented code assistant
zcode	Structured output generator
aihorde	Distributed inference network

These providers can be enabled in the dashboard and called via /v1/* endpoints without any API key when REQUIRE_API_KEY remains false.

Running OmniRoute Without API Keys

For local development or single-user deployments, leave REQUIRE_API_KEY unset or explicitly set it to false:

// Example: Calling a free provider without authentication
import fetch from 'node-fetch';

const response = await fetch('http://localhost:20128/v1/chat/completions', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    // No Authorization header required
  },
  body: JSON.stringify({
    model: 'opencode',  // Free, no-auth provider
    messages: [{ role: 'user', content: 'Explain recursion' }],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

This configuration works immediately after starting the server—no environment variables or key management needed.

Enforcing API Keys for All Traffic

To secure a production deployment, enable global API key enforcement:

# Environment configuration

export REQUIRE_API_KEY=true
export OMNIROUTE_API_KEY="your-secure-random-key"

Then include the key in all requests:

// Example: Authenticated request with enforced API key policy
const OMNIROUTE_API_KEY = process.env.OMNIROUTE_API_KEY;

const response = await fetch('http://localhost:20128/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${OMNIROUTE_API_KEY}`,  // Now required
  },
  body: JSON.stringify({
    model: 'openai-gpt-4o',  // Any provider, key now mandatory
    messages: [{ role: 'user', content: 'Summarize this article' }],
  }),
});

When REQUIRE_API_KEY is true, the policy in clientApi.ts rejects any request lacking a valid Bearer token matching OMNIROUTE_API_KEY or ROUTER_API_KEY.

Key Configuration Files

File Path	Purpose
src/shared/constants/featureFlagDefinitions.ts	Defines REQUIRE_API_KEY with default false
src/shared/constants/providers.ts	Lists FREE_APIKEY_PROVIDER_IDS (no-auth providers)
src/server/authz/policies/clientApi.ts	Runtime authorization policy implementation
src/shared/utils/clientApiRouteAuth.ts	Client-side auth helper and header parsing
src/shared/utils/featureFlags.ts	Runtime flag evaluation (isFeatureFlagEnabled)

Summary

• Default behavior: OmniRoute operates without requiring API keys—REQUIRE_API_KEY is false by default
• Free providers: qoder, opencode, dahl, auggie, zcode, and aihorde work with no credentials
• Enforcement toggle: Set REQUIRE_API_KEY=true to mandate keys for all providers and requests
• Policy location: Authorization logic lives in src/server/authz/policies/clientApi.ts with flag checks at lines 83-92

Frequently Asked Questions

Can I use OmniRoute completely without any API keys?

Yes. With REQUIRE_API_KEY left at its default false value, you can route requests to the free providers listed in FREE_APIKEY_PROVIDER_IDS without any authentication. This is ideal for local testing or isolated environments.

Does enabling REQUIRE_API_KEY affect upstream provider credentials?

No. The REQUIRE_API_KEY flag only controls whether clients must present a valid OmniRoute API key. Upstream provider credentials (like OpenAI or Anthropic keys) are configured separately in the dashboard and remain required for paid providers regardless of this setting.

How do I check if my OmniRoute instance requires API keys?

Query the feature flag status programmatically via src/shared/utils/featureFlags.ts:

import { isFeatureFlagEnabled } from './src/shared/utils/featureFlags';

const keysRequired = isFeatureFlagEnabled('REQUIRE_API_KEY');
console.log(`API keys enforced: ${keysRequired}`);

Or check the environment: echo $REQUIRE_API_KEY—empty or false means optional keys.

Can I require API keys for some providers but not others?

Not through the single REQUIRE_API_KEY flag. For per-provider access control, implement custom logic in src/server/authz/policies/clientApi.ts or use the dashboard's provider-level enablement toggles combined with key-based routing rules.

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