How OmniRoute Handles OAuth Authentication with LLM Providers Like Kimi

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 executes the following:

// 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 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 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.

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

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) 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. 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 injects the stored access token into the Authorization: Bearer <accessToken> header for every upstream request:

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 handles user authorization without exposing client secrets.
• Persistent connections stored via src/lib/db/connection.ts include rate-limiting metadata for granular cooldown control.
• Automatic refresh via src/sse/services/tokenRefresh.ts prevents token expiration from interrupting service.
• Circuit breakers and connection-level backoffs in src/shared/utils/circuitBreaker.ts isolate provider failures.
• Secure execution through open-sse/executors/kimi-web.ts injects bearer tokens while 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 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. 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. 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) 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.

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