# How to Configure Web Session Credentials for OAuth Providers in OmniRoute

> Learn how to configure web session credentials for OAuth providers in OmniRoute. Discover how OmniRoute securely encrypts and injects cookies or tokens into requests.

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

---

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

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

```bash

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

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