# How OmniRoute Handles OAuth Authentication with LLM Providers Like Kimi

> OmniRoute secures OAuth authentication with LLM providers like Kimi using a device-code flow. Discover how it manages tokens, automatic refresh, and resilient execution.

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

---

**OmniRoute implements a device-code OAuth flow for providers like Kimi, mapping tokens through a provider registry and managing persistence, automatic refresh, and resilient execution via dedicated auth services.**

OmniRoute treats every OAuth-enabled LLM provider as a first-class credential within its routing infrastructure. For providers such as **Kimi** (Moonshot AI), the system manages the complete authentication lifecycle—from initial device-code generation through automatic token refresh—using a combination of registry-based configuration, persistent connection storage, and circuit-breaker-protected execution layers.

## Device-Code Authentication Flow

OmniRoute utilizes the **OAuth 2.0 device authorization grant** for providers like Kimi, eliminating the need for client secrets in user-facing code while supporting headless and CLI environments.

### Provider Registration and Configuration

Every OAuth provider is defined in the provider registry located at `src/app/api/providers/[id]/test/oauthTestConfig.ts`. For Kimi, entries like `PROVIDERS["kimi-coding"]` and `PROVIDERS["kimi-web"]` specify the `deviceCodeUrl`, `tokenUrl`, `clientId`, required scopes, and a `mapTokens` function.

The registry entry normalizes provider-specific response formats into a standard internal structure containing `accessToken`, `refreshToken`, `expiresAt`, and optional `idToken` fields. This abstraction allows the core auth layer to handle Kimi identically to other OAuth providers despite differences in their raw API responses.

### Initiating the Login Flow

When a user initiates authentication via `/api/providers/kimi-coding/login`, the `requestDeviceCode` function in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts) executes the following:

```typescript
// Front-end call – kicks off the device-code flow
await fetch('/api/providers/kimi-coding/login', { method: 'POST' })
  .then(r => r.json())
  .then(({ verification_uri, user_code }) => {
    // Show user_code + verification_uri to the user
    console.log(`Enter ${user_code} at ${verification_uri}`);
  });

```

The service calls the provider-specific `deviceCodeUrl` and returns a **user code** and **verification URL** to the frontend. The user completes authorization on Kimi's website while the backend prepares to poll for the token.

### Polling and Token Mapping

The `pollToken` function in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts) repeatedly queries the provider's `tokenUrl` until the user completes authorization or a timeout occurs. This polling respects back-off rules defined in [`src/sse/services/cooldownAwareRetry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/cooldownAwareRetry.ts) to avoid rate limiting.

Once the token endpoint returns credentials, the provider-specific `mapTokens` function (e.g., `PROVIDERS["kimi-coding"].mapTokens`) transforms the raw OAuth response into the internal token format. This normalization ensures consistent handling of expiration timestamps and token types across different LLM providers.

```typescript
import { pollToken } from '@/sse/services/auth';

async function completeKimiOAuth(connectionId: string) {
  const pollResult = await pollToken('kimi-coding', connectionId);
  // `pollResult` contains the mapped tokens; they are persisted automatically
  console.log('OAuth completed, access token stored');
}

```

## Token Lifecycle Management

After acquisition, OmniRoute persists OAuth tokens as **connections** and manages their lifecycle through automated background processes.

### Persistent Connection Storage

Mapped tokens are stored in the connection table defined in [`src/lib/db/connection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/connection.ts). Each entry includes the `providerId` (e.g., `"kimi-coding"`), the token fields, and metadata for resilience handling such as `rateLimitedUntil` timestamps and `backoffLevel` counters.

This storage strategy isolates individual connections, allowing the system to apply rate-limiting cooldowns to specific OAuth credentials without affecting other users or providers.

### Automatic Token Refresh

A background job in [`src/sse/services/tokenRefresh.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/tokenRefresh.ts) periodically evaluates connections nearing expiration. For Kimi connections, it invokes `refreshKimiCodingToken` (or the generic `refreshOAuthToken`) when `expiresAt` approaches.

The refresh mechanism uses an `onPersist` callback to atomically update stored tokens, preventing race conditions during concurrent refresh attempts:

```typescript
import { refreshKimiCodingToken } from '@/sse/services/tokenRefresh';

async function refreshIfNeeded(conn) {
  if (conn.expiresAt - Date.now() < 5 * 60_000) { // < 5 min left
    await refreshKimiCodingToken(conn.id);
  }
}

```

## Resilience and Security Mechanisms

OmniRoute wraps OAuth authentication in multiple resilience layers to ensure provider outages or rate limits do not destabilize the routing pipeline.

### Circuit Breakers and Connection Cooldowns

The system implements a **provider circuit breaker** ([`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts)) that trips after a configurable number of consecutive 5xx failures from Kimi's OAuth endpoints. When open, the circuit breaker temporarily blocks all traffic to the provider, allowing the service to fail fast rather than queue requests against an unhealthy endpoint.

Additionally, **connection-level cooldowns** use the `rateLimitedUntil` and `backoffLevel` fields to isolate individual flaky OAuth tokens. If a specific Kimi refresh token consistently fails, only that connection enters a back-off state, preserving availability for other Kimi connections.

### Error Sanitization

All authentication errors flow through `buildErrorBody()` and `sanitizeErrorMessage()` in [`src/open-sse/utils/error.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/utils/error.ts). These functions strip raw stack traces and OAuth token data from responses before they reach the client, preventing accidental exposure of sensitive credentials in error messages.

## Request Execution with OAuth Tokens

When routing requests to Kimi models, the executor layer resolves the appropriate connection via `getExecutor("kimi-coding")`. The executor defined in [`open-sse/executors/kimi-web.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/kimi-web.ts) injects the stored access token into the `Authorization: Bearer <accessToken>` header for every upstream request:

```typescript
import { getExecutor } from '@/open-sse/executors/registry';

const exec = getExecutor('kimi-coding');
const response = await exec.execute({
  model: 'kimi-k2.6',
  messages: [{ role: 'user', content: 'Explain OAuth' }],
});

```

This execution model ensures that token management remains transparent to the routing logic while maintaining strict isolation between different providers' credential sets.

## Summary

- **Registry-based configuration** in `src/app/api/providers/[id]/test/oauthTestConfig.ts` defines OAuth endpoints and token mapping for Kimi and other providers.
- **Device-code flow** implementation in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts) handles user authorization without exposing client secrets.
- **Persistent connections** stored via [`src/lib/db/connection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/connection.ts) include rate-limiting metadata for granular cooldown control.
- **Automatic refresh** via [`src/sse/services/tokenRefresh.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/tokenRefresh.ts) prevents token expiration from interrupting service.
- **Circuit breakers** and connection-level backoffs in [`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts) isolate provider failures.
- **Secure execution** through [`open-sse/executors/kimi-web.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/kimi-web.ts) injects bearer tokens while [`src/open-sse/utils/error.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/utils/error.ts) sanitizes error responses.

## Frequently Asked Questions

### What OAuth flow does OmniRoute use for Kimi?

OmniRoute uses the **OAuth 2.0 device authorization grant** (device-code flow) for Kimi authentication. This flow is implemented in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts) and involves requesting a device code from Kimi's `deviceCodeUrl`, displaying a user code to the end user, and polling the `tokenUrl` until authorization completes.

### How does OmniRoute handle token expiration?

OmniRoute handles expiration through a background token refresh service defined in [`src/sse/services/tokenRefresh.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/tokenRefresh.ts). The service periodically checks the `expiresAt` field of each connection and calls provider-specific refresh functions (like `refreshKimiCodingToken`) to obtain new access tokens before the current ones expire.

### Where are OAuth tokens stored in OmniRoute?

OAuth tokens are persisted in the **connection table** managed by [`src/lib/db/connection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/connection.ts). Each record includes the mapped `accessToken`, `refreshToken`, `expiresAt`, provider identifier, and rate-limiting metadata such as `rateLimitedUntil` and `backoffLevel`.

### How does OmniRoute protect against OAuth provider failures?

The system employs a **circuit breaker** pattern ([`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts)) that monitors consecutive failures to OAuth endpoints and temporarily halts requests when thresholds are exceeded. Additionally, individual connections track their own cooldown states, allowing the system to isolate problematic credentials without affecting healthy connections to the same provider.