How to Set Up OAuth Authentication for Claude Code, Cursor, and Codex in OmniRoute

Set up OAuth for Claude Code, Cursor, and Codex by registering apps with each provider, adding credentials to OmniRoute's .env file using the OMNIROUTE_OAUTH_* pattern, enabling the provider in the dashboard UI, and running omniroute auth login --provider=<name> to authenticate.

OmniRoute supports OAuth authentication for Claude Code, Cursor, and Codex, enabling secure token-based access without hardcoding API keys. This configuration delegates authorization to the upstream providers while OmniRoute handles token storage, refresh, and injection into proxied requests. Follow these steps to configure OAuth using the exact environment variable patterns and file paths defined in the OmniRoute source code.

Register OAuth Applications with Providers

Before configuring OmniRoute, register an OAuth application with each provider's developer console. For Claude Code, use the Anthropic console; for Cursor, use the Cursor platform; and for Codex, use the respective Codex service portal. Upon registration, each provider issues a client ID and client secret that OmniRoute will use to initiate the authorization flow.

Configure Environment Variables

OmniRoute reads OAuth credentials from environment variables following the pattern OMNIROUTE_OAUTH_<PROVIDER>_CLIENT_ID and OMNIROUTE_OAUTH_<PROVIDER>_CLIENT_SECRET. Add these to your project's .env file:

# Claude Code OAuth

OMNIROUTE_OAUTH_CLAUDE_CLIENT_ID=your-claude-client-id
OMNIROUTE_OAUTH_CLAUDE_CLIENT_SECRET=your-claude-client-secret

# Cursor OAuth

OMNIROUTE_OAUTH_CURSOR_CLIENT_ID=your-cursor-client-id
OMNIROUTE_OAUTH_CURSOR_CLIENT_SECRET=your-cursor-client-secret

# Codex OAuth

OMNIROROUTE_OAUTH_CODEX_CLIENT_ID=your-codex-client-id
OMNIROUTE_OAUTH_CODEX_CLIENT_SECRET=your-codex-client-secret

These variables are injected into the provider configuration at runtime. The central registry defining these OAuth-enabled providers resides in src/shared/constants/providers/oauth.ts at line 92, where each provider is declared with "type": "oauth".

Enable OAuth in the Dashboard

Navigate to the Settings page in the OmniRoute dashboard. Locate the toggle labeled "Enable Claude Code OAuth" (or the equivalent for Cursor and Codex). Activating this switch instructs OmniRoute to use the OAuth flow instead of API-key authentication for that provider.

The UI logic handling these toggles is implemented in src/app/(dashboard)/dashboard/providers/[id]/hooks/useProviderSettings.ts, specifically lines 218-232, which persist the OAuth preference to the backend and update the provider state.

Authenticate via the CLI

With credentials configured and the provider enabled, initiate the OAuth flow using OmniRoute's built-in CLI helper. This command launches the provider's consent screen in your default browser:

# Claude Code

omniroute auth login --provider=claude

# Cursor

omniroute auth login --provider=cursor

# Codex

omniroute auth login --provider=codex

The CLI tool registry that maps these commands to provider IDs is defined in src/shared/constants/cliTools.ts at lines 13-16. This registry ensures the claude argument correctly triggers the OAuth flow for the Claude Code provider.

OAuth Callback and Token Storage

After you authorize the application in the browser, the provider redirects to OmniRoute's callback endpoint at /api/oauth/callback/<provider>. The Next.js route handler in src/app/api/oauth/callback/[provider]/route.ts receives the authorization code, exchanges it for an access token, and stores the credentials securely in the encrypted SQLite database.

Token Refresh

OmniRoute's background token-refresh service, defined in src/lib/oauth/constants/oauth.ts, periodically checks token expiry. It automatically refreshes access tokens using stored refresh tokens, maintaining active sessions without requiring user interaction or CLI re-authentication.

Making Authenticated Requests

Once authenticated, subsequent API calls (for example, POST /v1/chat/completions) automatically include the stored bearer token. The request pipeline detects provider-specific headers (x-omniroute-oauth-token) and constructs the upstream request with the appropriate Authorization: Bearer <token> header, as implemented in the core OAuth handling logic.

Summary

• Register OAuth applications with Anthropic (Claude Code), Cursor, and Codex to obtain client IDs and secrets.
• Configure environment variables using the OMNIROUTE_OAUTH_<PROVIDER>_CLIENT_ID and OMNIROUTE_OAUTH_<PROVIDER>_CLIENT_SECRET pattern in src/shared/constants/providers/oauth.ts.
• Enable the provider via the dashboard toggle handled in useProviderSettings.ts (lines 218-232).
• Execute omniroute auth login --provider=<name> to authenticate through the browser flow defined in src/shared/constants/cliTools.ts.
• Tokens are stored securely and refreshed automatically via the callback handler at src/app/api/oauth/callback/[provider]/route.ts and the background service in src/lib/oauth/constants/oauth.ts.

Frequently Asked Questions

What redirect URI should I configure in the provider's OAuth settings?

Configure the redirect URI to point to OmniRoute's callback endpoint: http://<your-omniroute-host>/api/oauth/callback/<provider>. For example, use /api/oauth/callback/claude for Claude Code. This path is handled by the dynamic route in src/app/api/oauth/callback/[provider]/route.ts.

Where are the OAuth tokens stored after authentication?

OmniRoute stores access and refresh tokens in an encrypted SQLite database. The encryption ensures credentials remain secure at rest, and the background service in src/lib/oauth/constants/oauth.ts handles automatic refresh without exposing tokens in application memory longer than necessary.

Can I use both OAuth and API key authentication for the same provider?

No. OmniRoute treats authentication methods as mutually exclusive per provider. When you enable the OAuth toggle in the dashboard UI (as implemented in useProviderSettings.ts), the system ignores any configured API keys and exclusively uses the OAuth token flow for that provider, referencing the variables defined in src/shared/constants/providers/oauth.ts.

How do I revoke OAuth access for a specific provider?

To revoke access, disable the provider in the OmniRoute dashboard UI or delete the stored tokens from the database. Additionally, you must revoke the application permission in the provider's own developer console (Anthropic for Claude Code, Cursor, or Codex) to invalidate the refresh tokens and prevent OmniRoute from obtaining new access tokens.

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