How to Configure Web Session Credentials for OAuth Providers in OmniRoute

OmniRoute stores OAuth web session credentials (cookies or tokens) in an encrypted credential blob via the Paste-Credentials API, automatically injecting them into outgoing requests at runtime.

OmniRoute is an open-source routing layer that normalizes access to multiple AI providers. When integrating OAuth-based services that require browser-style session data rather than static API keys, you must configure web session credentials through a specialized encrypted storage system. This guide explains how to set up session cookies and tokens using the Paste-Credentials API, based on the current implementation in diegosouzapw/OmniRoute.

Understanding Web Session Credentials

Web session credentials differ from standard API keys because they represent transient authentication state typically established through browser-based OAuth flows. In OmniRoute, these are handled as credential blobs that the system injects into HTTP headers at request time.

Providers define their requirements in the webSessionCredential metadata field. For example, in src/lib/oauth/providers/claude.ts, the metadata specifies whether the provider needs a cookie string, a token, or both. This definition drives both the UI rendering and the validation logic.

Credential Types Supported

OmniRoute handles two primary forms of web session data:

• Cookie-based sessions: Raw cookie strings copied directly from browser dev tools, such as sessionid=abc123; __Secure-next-auth.session-token=def456.
• Token-based sessions: Explicit session tokens sent as headers or query parameters, formatted as token=xyz.

The Credential Storage Architecture

All web session data persists in a centralized, encrypted credential blob managed by src/lib/oauth/credentialBlob.ts. When you submit credentials via the API, OmniRoute calls credentialBlob.save(providerId, data), which encrypts the payload and stores it in the SQLite credential_blob table.

At runtime, when routing requests to the provider, the executor calls credentialBlob.load(providerId) to retrieve and decrypt the data. The executor—typically implemented in src/open-sse/executors/default.ts—then injects the session information into the outgoing request, usually as a Cookie header, before forwarding traffic to the upstream service.

Step-by-Step Configuration

Follow these steps to configure web session credentials for any supported OAuth provider.

1. Locate Provider Metadata

First, identify the required credential keys by examining the provider definition file in src/lib/oauth/providers/<provider>.ts. Look for the webSessionCredential field, which lists the expected keys (e.g., cookie, token) and their UI placeholders.

For instance, the Claude provider defines cookie as the required key, while others like Notion may require both a cookie and a CSRF token separated by semicolons.

2. Submit Credentials via the Paste-Credentials API

OmniRoute exposes a generic endpoint at src/app/api/oauth/[provider]/paste-credentials/route.ts that accepts raw session strings.

Send a POST request to /api/oauth/{provider}/paste-credentials/route with a JSON payload containing your session data:

{
  "session": "sessionid=abc123; __Secure-next-auth.session-token=def456"
}

The API validates the input against the provider's metadata, then encrypts and persists the blob using credentialBlob.save().

3. Verify Runtime Injection

To confirm the credential is active, execute a test request through OmniRoute and inspect the server logs or the outgoing headers in src/open-sse/executors/default.ts. You should observe the Cookie header populated with your stored session data.

Administrators can also query stored credentials (encrypted) via GET /api/oauth/{provider}/paste-credentials/route or inspect the credential_blob table directly in SQLite.

Practical Example: Claude Web Session

The following example demonstrates configuring a Claude web session using curl:

# Extract the cookie string from your browser's developer tools

COOKIE="sessionid=abc123; __Secure-next-auth.session-token=def456"

# Submit to OmniRoute's Paste-Credentials endpoint

curl -X POST "https://your-omniroute-host/api/oauth/claude/paste-credentials/route" \
     -H "Content-Type: application/json" \
     -d "{\"session\":\"${COOKIE}\"}"

Upon success, the API returns HTTP 200. The encrypted credential is now stored and will be automatically injected as a Cookie header into all Claude provider requests handled by the executor.

Managing and Rotating Credentials

Web session credentials often expire. OmniRoute supports updating and deleting credentials without restarting the service.

Updating Existing Credentials

To rotate a session cookie or token, simply repeat the POST request to the paste-credentials endpoint with the new value. The credentialBlob.save() method overwrites the existing entry for that provider ID.

Removing Credentials

To delete a credential entirely, send a DELETE request to the same endpoint:

curl -X DELETE "https://your-omniroute-host/api/oauth/claude/paste-credentials/route"

This clears the entry from the encrypted credential store immediately.

Provider-Specific Implementation Details

Different OAuth providers impose unique requirements on web session handling.

Claude-Web and Turnstile Challenges

The Claude provider (src/lib/oauth/providers/claude.ts) may trigger a Turnstile (CAPTCHA) challenge during session establishment. In these cases, the session cookie is automatically refreshed after challenge completion. Ensure your session string includes any secondary tokens required post-verification.

Multi-Key Providers (Notion Example)

Some providers require multiple distinct values in the session payload. For example, Notion expects both a cookie and a CSRF token. The webSessionCredential metadata lists both keys, and you must provide them in the session string separated by semicolons, exactly as they appear in your browser's request headers.

Summary

• Web session credentials (cookies/tokens) for OAuth providers are stored in an encrypted blob via src/lib/oauth/credentialBlob.ts.
• Use the Paste-Credentials API at /api/oauth/{provider}/paste-credentials/route to submit raw session strings.
• Runtime injection is handled by the executor in src/open-sse/executors/default.ts, which loads credentials via credentialBlob.load().
• Update credentials by re-posting; delete them via the DELETE method to the same endpoint.
• Provider metadata in src/lib/oauth/providers/{provider}.ts defines required keys and validation rules.

Frequently Asked Questions

How do I know if a provider requires web session credentials instead of an API key?

Check the provider's definition file in src/lib/oauth/providers/{provider}.ts. If the file exports a webSessionCredential object with required keys like cookie or token, the provider expects web session data. Traditional API key providers use an apiKey or token field at the root level of their configuration object.

Where is the session data stored and is it encrypted?

Session data is stored in the SQLite credential_blob table using AES-256 encryption via the credentialBlob.ts utility. The blob is encrypted at rest and only decrypted in memory when the request executor loads it for active routing.

Can I configure multiple web session credentials for the same provider?

No, OmniRoute maintains a single credential blob per provider ID. If you need to switch between multiple sessions (e.g., different user accounts), you must overwrite the existing credential via the Paste-Credentials API or implement provider aliases at the routing layer.

What happens if the session cookie expires during a request?

OmniRoute does not automatically refresh expired cookies for providers like Claude-Web. If the upstream service returns a 401 or 403 due to invalid session data, the request will fail. You must manually update the credential via the POST endpoint or implement a custom refresh handler in the provider's executor logic at src/open-sse/executors/{provider}.ts.

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