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

> Effortlessly set up OAuth for Claude Code, Cursor, and Codex in OmniRoute. Securely authenticate your applications by following our simple step-by-step guide and integrating credentials via the .env file.

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

---

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

```dotenv

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/oauth.ts).
- Enable the provider via the dashboard toggle handled in [`useProviderSettings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/useProviderSettings.ts) (lines 218-232).
- Execute `omniroute auth login --provider=<name>` to authenticate through the browser flow defined in [`src/shared/constants/cliTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.