How to Set Up OAuth Providers for Claude Code, Codex CLI, Grok Build, and Cursor in OmniRoute

OmniRoute stores OAuth credentials in its SQLite database and automatically refreshes tokens via the generic token-refresh service at src/sse/services/tokenRefresh.ts, enabling seamless authentication for Claude Code, Codex CLI, Grok Build, and Cursor.

OmniRoute treats these four AI coding assistants as OAuth-enabled providers, with their catalog definitions located in src/shared/constants/providers/oauth.ts. Whether you prefer the web dashboard or the command line, this guide covers the exact steps to configure each provider and validate the connection.

Prerequisites

Before adding providers, ensure OmniRoute is running locally on port 20128 and you have access to the CLI (omniroute from npm). You will need existing accounts with Anthropic (Claude Code), OpenAI (Codex CLI), xAI (Grok Build), or Cursor, along with their respective local authentication files or browser access for OAuth flows.

Provider-Specific Configuration

Claude Code (Anthropic)

Claude Code requires either a Google sign-in flow or a local token file stored at ~/.claude/auth.json. In OmniRoute, this provider uses the ID claude (short ID cc).

Dashboard Method:

1. Open the OmniRoute dashboard at http://localhost:20128.

2. Navigate to Settings → Providers → Add Provider.

3. Select Claude Code from the list.

4. Click Import token. OmniRoute automatically reads ~/.claude/auth.json, or you can paste the JSON contents manually.

5. Save the connection. The provider is now stored as type oauth with ID claude.

CLI Method:

omniroute provider add --id=claude --type=oauth

Follow the interactive prompts to paste the auth.json contents or permit the CLI to open a browser for Google sign-in.

Codex CLI (OpenAI)

Codex CLI writes its authentication token to ~/.codex/auth.json. OmniRoute imports this file using the same mechanism as Claude Code.

Dashboard Method:

1. In the dashboard, click Add Provider and select Codex.

2. Click Import token to read from ~/.codex/auth.json.

3. Confirm the import and save.

CLI Method:

omniroute provider add --id=codex --type=oauth

Paste the token from ~/.codex/auth.json when prompted by the interactive shell.

Grok Build (xAI)

Grok Build uses provider ID grok-cli. You can authenticate using either the full ~/.grok/auth.json file or a raw JWT access token extracted from that file.

Dashboard Method:

1. Add a new provider and choose Grok Build.

2. In the Auth Hint box, paste the entire contents of ~/.grok/auth.json or only the JWT string from the access_token field.

3. Save. OmniRoute extracts the refresh_token and manages automatic rotation via src/sse/services/tokenRefresh.ts.

CLI Method:

omniroute provider add --id=grok-cli --type=oauth

When prompted, provide either the JSON file contents or the raw JWT token.

Cursor IDE

Cursor uses an OAuth device flow rather than a static token file. OmniRoute initiates this flow and displays a verification code for you to enter on Cursor's authorization page.

Dashboard Method:

1. Add a provider and select Cursor IDE (ID cursor).

2. Click Sign in via browser. OmniRoute launches the OAuth device flow and displays a unique code.

3. Copy the code into the Cursor sign-in page at https://cursor.com/oauth/device.

4. After authorization, OmniRoute receives the access token and persists it to the SQLite database.

CLI Method:

omniroute provider add --id=cursor --type=oauth

The CLI displays the device-flow code and URL. Open your browser, navigate to the provided URL, and enter the code to complete authentication.

Post-Setup Validation and Configuration

After configuring any OAuth provider, complete these verification steps and optional enhancements.

Validate the Connection

Check that OmniRoute successfully registered the provider by inspecting the dashboard for a green checkmark next to the provider name. Alternatively, test the API directly:

curl -H "Authorization: Bearer <OMNIRoute_API_KEY>" http://localhost:20128/v1/models

A successful response lists available models prefixed with the provider ID, such as claude/anthropic/claude-3-opus-20240229.

Enable Optional Feature Flags

OmniRoute includes feature flags to customize OAuth provider behavior. Locate these in Settings → Feature Flags:

• CLAUDE_CODE_COMPATIBLE_PROVIDER: Enabled by default. Toggle this to block or allow Claude Code-specific behaviors.
• AUTO_SYNC_CLAUDE_PROFILES: When enabled, OmniRoute automatically writes profile configurations to ~/.claude/profiles/<name>/settings.json after each model sync. This logic is implemented in src/lib/cli-helper/claudeProfileAutoSync.ts.

Configure Discovery Aliases

To expose non-Claude models to Claude Code during its discovery phase, map them using the Discovery Alias endpoint. This allows Claude Code to see third-party models as claude/<provider>/<model>:

// src/app/api/providers/[id]/cc-alias/route.ts
// POST to /api/providers/{providerId}/cc-alias

This route overrides the default model discovery behavior for the specified provider ID.

Summary

• OmniRoute defines OAuth providers in src/shared/constants/providers/oauth.ts and stores credentials in its SQLite database via src/lib/db/*.
• Claude Code uses ID claude and reads from ~/.claude/auth.json.
• Codex CLI uses ID codex and reads from ~/.codex/auth.json.
• Grok Build uses ID grok-cli and accepts either a JSON file or raw JWT.
• Cursor uses ID cursor and requires an interactive OAuth device flow.
• All providers support automatic token refresh via src/sse/services/tokenRefresh.ts.
• Enable AUTO_SYNC_CLAUDE_PROFILES for automatic Claude Code profile synchronization.

Frequently Asked Questions

Where does OmniRoute store OAuth tokens for these providers?

OmniRoute persists OAuth credentials, including access tokens and refresh tokens, in its local SQLite database through the database layer at src/lib/db/*. The system never stores tokens in plain text files and automatically handles encryption at rest according to the application's security configuration.

How does OmniRoute handle token expiration for Claude Code and Grok Build?

OmniRoute uses the generic token-refresh service defined in src/sse/services/tokenRefresh.ts. When a token nears expiration, the system automatically calls the provider's refresh endpoint using the stored refresh_token, updates the database with the new credentials, and maintains the connection without user intervention.

Can I configure these OAuth providers without using the OmniRoute web dashboard?

Yes. The OmniRoute CLI supports headless configuration using the omniroute provider add --id=<provider-id> --type=oauth command. For Cursor specifically, the CLI outputs the device-flow code and URL directly in the terminal, allowing you to complete authorization in a browser without accessing the dashboard UI.

What is the difference between the provider IDs claude and cc?

In OmniRoute's catalog at src/shared/constants/providers/oauth.ts, claude is the canonical provider ID for Claude Code, while cc acts as a short identifier or alias used in certain API routes and internal references. Both refer to the same Anthropic OAuth integration, but CLI commands and database entries typically use the full claude identifier.

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