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

> Learn how to set up OAuth providers for Claude Code, Codex CLI, Grok Build, and Cursor in OmniRoute. Securely manage credentials and enable seamless authentication with this guide.

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

---

**OmniRoute stores OAuth credentials in its SQLite database and automatically refreshes tokens via the generic token-refresh service at [`src/sse/services/tokenRefresh.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:**

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

```

Follow the interactive prompts to paste the [`auth.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:**

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/tokenRefresh.ts).

**CLI Method:**

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

```bash
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:

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

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