# How to Add a Custom Provider to the OmniRoute Provider Registry

> Learn to add a custom provider to the OmniRoute provider registry. Select authentication, insert provider definition, and run Zod validation for schema compliance.

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

---

**Adding a custom provider to the OmniRoute provider registry requires selecting the appropriate authentication category, inserting a provider definition object into the corresponding constants file under `src/shared/constants/providers/`, and running the Zod validation suite to ensure schema compliance.**

OmniRoute unifies LLM providers under a single routing system that powers UI listings, API validation, and request handling. To extend the platform with a new service, you must register your provider in the centralized registry located in `src/shared/constants/providers/`. This guide walks through the exact file paths, required schema fields, and validation steps needed to add a custom provider to the OmniRoute provider registry without breaking existing functionality.

## Choose the Authentication Category

OmniRoute organizes providers by authentication method. You must select the correct category before inserting your definition.

- **No-auth**: Providers requiring no credentials (e.g., free open-source models). File: [`src/shared/constants/providers/noauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/noauth.ts)
- **OAuth**: Providers using OAuth flows (e.g., Anthropic, GitHub Copilot). File: [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts)
- **API-key**: Bearer-style key authentication. File: [`src/shared/constants/providers/apikey/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/apikey/index.ts)
- **Web-cookie**: Session-based providers (e.g., Google Search). File: [`src/shared/constants/providers/web-cookie.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/web-cookie.ts)
- **Local/Self-hosted**: Self-hosted model servers (e.g., Ollama, LM Studio). File: [`src/shared/constants/providers/local.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/local.ts)

Most third-party LLM services use either **OAuth** or **API-key** authentication.

## Insert the Provider Definition

Open the file matching your selected category and insert a new object literal into the exported constants object.

### Required Schema Fields

The Zod schema in [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts) enforces the following required fields:

| Field | Description |
|-------|-------------|
| `id` | Unique stable identifier used throughout the system |
| `name` | Human-readable display name |
| `icon` | Icon name from the built-in UI library |
| `color` | Brand hex color code |
| `subscriptionRisk` | Boolean indicating if paid subscription is required |
| `riskNoticeVariant` | One of: `oauth`, `webCookie`, `deprecated`, `embedded-service` |

Optional fields include `alias` (short CLI name), `authHint` (UI help text), `hasFree` (free tier indicator), and `website`.

### Example: OAuth Provider Definition

```typescript
// src/shared/constants/providers/oauth.ts (lines 5-219)
export const OAUTH_PROVIDERS = {
  // Existing providers...
  exampleai: {
    id: "exampleai",
    alias: "exa",
    name: "ExampleAI",
    icon: "smart_toy",
    color: "#123456",
    subscriptionRisk: true,
    riskNoticeVariant: "oauth",
    authHint: "Paste the OAuth token from the ExampleAI dashboard.",
    hasFree: true,
  },
};

```

### Automatic Registration via Global Registry

You do not need to manually import new entries. The global registry at [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) (lines 13-22) automatically imports all category files:

```typescript
// src/shared/constants/providers.ts
import { NOAUTH_PROVIDERS } from "./providers/noauth";
import { OAUTH_PROVIDERS } from "./providers/oauth";
import { APIKEY_PROVIDERS } from "./providers/apikey";
import { WEB_COOKIE_PROVIDERS } from "./providers/web-cookie";
import { LOCAL_PROVIDERS } from "./providers/local";
// ... additional imports

export const AI_PROVIDERS = {
  ...NOAUTH_PROVIDERS,
  ...OAUTH_PROVIDERS,
  ...APIKEY_PROVIDERS,
  // ... merged categories
};

```

Because the aggregator merges entire category objects, your new entry becomes immediately available system-wide upon saving the file.

## Validate the Provider Configuration

The codebase validates every provider category against the Zod schema at the bottom of [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) (lines 32-43):

```typescript
import { validateProviders } from "../validation/providerSchema";

validateProviders(NOAUTH_PROVIDERS, "NOAUTH_PROVIDERS");
validateProviders(OAUTH_PROVIDERS, "OAUTH_PROVIDERS");
validateProviders(APIKEY_PROVIDERS, "APIKEY_PROVIDERS");
// ... additional validations

```

Run the validation suite to verify your configuration:

```bash
npm run typecheck:core

# Or complete verification:

npm run lint && npm run test

```

If fields fail validation, the Zod schema will output specific error messages indicating the offending property.

## Implement Custom Request Handling (Optional)

OpenAI-compatible providers work automatically with the default executor at [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts). For non-standard APIs, you must:

1. Create a new executor under `open-sse/executors/` extending `BaseExecutor`
2. Register it in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts) within the `getExecutor()` factory
3. Add a translator in `open-sse/translator/` if request/response formats differ

See [`docs/frameworks/EXECUTORS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/EXECUTORS.md) in the repository for detailed implementation guidelines.

## Complete Example: Adding an API-Key Provider

Below is a complete implementation for an imaginary **FastAI** provider using API-key authentication:

```typescript
// src/shared/constants/providers/apikey/index.ts (lines 1-120)
export const APIKEY_PROVIDERS = {
  // Existing providers...
  fastai: {
    id: "fastai",
    alias: "fa",
    name: "FastAI",
    icon: "bolt",
    color: "#00A8E8",
    subscriptionRisk: false,
    riskNoticeVariant: "apikey",
    authHint: "Paste your FastAI API key (Bearer token).",
    hasFree: true,
  },
};

```

After committing this change, run the validation commands. Upon successful completion, the provider appears in the **"Add Provider"** dropdown, becomes selectable in the UI, and integrates with the routing engine.

## Summary

- **Select the authentication category** that matches your provider's credential requirements (OAuth, API-key, No-auth, etc.)
- **Insert the provider definition** into the appropriate file under `src/shared/constants/providers/`, ensuring all required schema fields are present
- **Run Zod validation** using `npm run typecheck:core` to confirm schema compliance before deployment
- **(Optional) Implement custom executors** in `open-sse/executors/` for non-OpenAI-compatible request formats

## Frequently Asked Questions

### What fields are required when adding a provider to the OmniRoute registry?

The Zod schema requires six fields: `id` (unique identifier), `name` (display name), `icon` (UI library reference), `color` (brand hex), `subscriptionRisk` (boolean for paid tiers), and `riskNoticeVariant` (one of four authentication variants). Optional fields like `alias`, `authHint`, and `hasFree` enhance CLI and UI usability but are not mandatory.

### How does the global registry recognize my new provider?

The global registry at [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) imports entire category files (lines 13-22) and merges them into the exported `AI_PROVIDERS` proxy. Because it imports the constant objects by reference, any new entry added to [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts) or similar files automatically appears in the system without manual registration.

### Where is the validation logic defined for provider schemas?

Validation occurs in [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts) using the `validateProviders()` function. This Zod-based validator checks each provider object against strict type definitions and runs at the bottom of [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) (lines 32-43) for every authentication category.

### Do I need custom code for API request handling?

Only if your provider deviates from the OpenAI API format. Standard OpenAI-compatible providers use the default executor at [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts). For custom request shapes, create a new executor in `open-sse/executors/` and register it in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts), optionally adding a translator in `open-sse/translator/` for payload transformation.