# How to Set Up OAuth with Kimi-Code: A Complete Implementation Guide

> Effortlessly set up OAuth with Kimi-Code using our comprehensive guide. Learn to configure the OAuth host and implement the device-code flow for seamless authentication. SDK manages tokens automatically.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: how-to-guide
- Published: 2026-08-14

---

**Set up OAuth with Kimi-Code by configuring the OAuth host, instantiating `KimiOAuthToolkit`, and running the device-code flow through `toolkit.login()` — the SDK handles token persistence, automatic refresh, and cross-process locking automatically.**

The **@moonshot-ai/kimi-code** SDK includes a self-contained OAuth implementation that eliminates external dependencies. This guide walks through the complete setup process using the actual source architecture from the MoonshotAI/kimi-code repository, covering configuration, authentication flows, token management, and Kimi-specific API integration.

## OAuth Architecture Overview

Kimi-Code's OAuth system consists of three coordinated components:

| Component | Responsibility | Source Location |
|-----------|--------------|---------------|
| **Flow Configuration** | Defines OAuth host and client parameters | [[`packages/oauth/src/constants.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/constants.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/constants.ts) |
| **OAuthManager** | Token storage, refresh, device-code orchestration, file locking | [[`packages/oauth/src/oauth-manager.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/oauth-manager.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/oauth-manager.ts) |
| **KimiOAuthToolkit** | High-level façade with login/logout/status methods and Kimi API helpers | [[`packages/oauth/src/toolkit.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/toolkit.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/toolkit.ts) |

## Step 1: Configure the OAuth Host (Optional)

By default, Kimi-Code connects to `https://auth.kimi.com`. For private deployments, set either environment variable before importing the SDK:

```bash
export KIMI_CODE_OAUTH_HOST="https://my-kimi-instance.com"

# Legacy fallback also supported:

export KIMI_OAUTH_HOST="https://my-kimi-instance.com"

```

The `KIMI_CODE_FLOW_CONFIG` constant in [`constants.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/constants.ts) (lines 5-19) reads these variables and constructs the flow configuration. If neither variable is set, the SDK falls back to the production Kimi auth server.

## Step 2: Create a KimiOAuthToolkit Instance

The **KimiOAuthToolkit** class is the primary entry point for OAuth with Kimi-Code. Instantiate it with defaults or custom options:

```typescript
import { KimiOAuthToolkit } from '@moonshot-ai/kimi-code/oauth';

// Default: stores tokens at ~/.kimi-code/credentials
const toolkit = new KimiOAuthToolkit();

```

For custom storage locations:

```typescript
import { KimiOAuthToolkit } from '@moonshot-ai/kimi-code/oauth';
import { join } from 'node:path';
import { homedir } from 'node:os';

const toolkit = new KimiOAuthToolkit({
  homeDir: join(homedir(), '.my-kimi')
});

```

The constructor accepts `homeDir`, custom `fetch` implementations for non-Node environments, and other storage configurations.

## Step 3: Execute the Device-Code Login Flow

Call `toolkit.login()` to initiate the **OAuth Device Code** flow. This opens a browser for user authorization and handles polling automatically:

```typescript
async function authenticate() {
  const toolkit = new KimiOAuthToolkit();
  
  const result = await toolkit.login(); // provider defaults to "kimi-code"
  console.log('Authenticated with provider:', result.providerName);
}

authenticate().catch(console.error);

```

The underlying **OAuthManager** orchestrates three phases defined in [`packages/oauth/src/oauth.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/oauth.ts):

1. **Request device code** — `requestDeviceAuthorization()` creates `user_code` and `verification_uri_complete` (lines 19-58)
2. **Poll token endpoint** — `pollDeviceToken()` checks status until `success`, `denied`, `expired`, or `pending` (lines 68-111)
3. **Token refresh** — `refreshAccessToken()` exchanges refresh tokens (lines 126-190)

### Custom Device Code Display

Override the default browser-opening behavior with the `onDeviceCode` hook:

```typescript
await toolkit.login(undefined, {
  onDeviceCode: async (auth) => {
    console.log(`Enter code ${auth.userCode} at ${auth.verificationUriComplete}`);
    // Custom: send to Slack, display in UI, etc.
  }
});

```

## Step 4: Obtain and Use Access Tokens

The toolkit provides two token retrieval patterns for OAuth with Kimi-Code:

### Direct Token Access

```typescript
const token = await toolkit.getCachedAccessToken();
// Returns string or undefined; does NOT refresh automatically

```

### BearerTokenProvider (Auto-Refreshing)

For long-running applications, use the provider that automatically refreshes:

```typescript
const bearer = toolkit.tokenProvider(); // KimiOAuthToolkit.tokenProvider()

async function callProtectedApi(url: string) {
  const token = await bearer.getAccessToken(); // Triggers OAuthManager.ensureFresh()
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` }
  });
  return response.json();
}

```

The `ensureFresh()` method in [`oauth-manager.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/oauth-manager.ts) (lines 54-82) checks token expiration and triggers refresh when within the renewal window.

## Step 5: Logout and Credential Cleanup

Remove stored tokens and provisioned configuration:

```typescript
await toolkit.logout();
// Deletes token file via OAuthManager.logout() (oauth-manager.ts lines 46-48)

```

Verify removal:

```typescript
const cached = await toolkit.getCachedAccessToken();
console.log(cached); // undefined

```

## Step 6: Access Kimi-Specific APIs

The toolkit wraps Kimi-managed endpoints for usage, user info, and feedback:

```typescript
// Fetch usage quota and limits
const usage = await toolkit.getManagedUsage();

if (usage.kind === 'ok') {
  console.log('Limits:', usage.limits);
  console.log('Current usage:', usage.current);
} else {
  console.error('Failed:', usage.message);
}

```

These methods use `fetchManagedUsage` and related helpers in [`src/managed-usage.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/managed-usage.ts), automatically injecting the bearer token from your OAuth session.

## Complete Working Examples

### Example 1: Full Login and Token Display

```typescript
import { KimiOAuthToolkit } from '@moonshot-ai/kimi-code/oauth';

async function main() {
  const toolkit = new KimiOAuthToolkit();

  await toolkit.login(undefined, {
    onDeviceCode: (auth) => {
      console.log(`🔑 Code: ${auth.userCode}`);
      console.log(`🌐 Visit: ${auth.verificationUriComplete}`);
    }
  });

  const token = await toolkit.getCachedAccessToken();
  console.log('Access token:', token);
}

main().catch(console.error);

```

### Example 2: Auto-Refreshing API Client

```typescript
import { KimiOAuthToolkit } from '@moonshot-ai/kimi-code/oauth';

async function queryKimiApi() {
  const toolkit = new KimiOAuthToolkit();
  const bearer = toolkit.tokenProvider();

  const response = await fetch('https://api.kimi.com/v1/user', {
    headers: {
      Authorization: `Bearer ${await bearer.getAccessToken()}`
    }
  });
  
  const userData = await response.json();
  console.log('User:', userData);
}

queryKimiApi().catch(console.error);

```

### Example 3: Session Cleanup

```typescript
import { KimiOAuthToolkit } from '@moonshot-ai/kimi-code/oauth';

async function cleanup() {
  const toolkit = new KimiOAuthToolkit();
  
  await toolkit.logout();
  const remaining = await toolkit.getCachedAccessToken();
  
  console.assert(remaining === undefined, 'Token should be removed');
  console.log('Logout successful');
}

cleanup().catch(console.error);

```

## Source File Reference

Understanding these files deepens your ability to customize OAuth with Kimi-Code:

| File | Purpose |
|------|---------|
| [[`constants.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/constants.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/constants.ts) | OAuth host configuration, environment variable parsing |
| [[`types.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/types.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/types.ts) | TypeScript interfaces for tokens, flows, and responses |
| [[`oauth.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/oauth.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/oauth.ts) | HTTP layer: device authorization, token polling, refresh |
| [[`oauth-manager.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/oauth-manager.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/oauth-manager.ts) | Core lifecycle: storage, refresh, locking, flow coordination |
| [[`toolkit.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/toolkit.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/toolkit.ts) | Public API façade combining manager with Kimi helpers |
| [[`storage.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/storage.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/storage.ts) | `FileTokenStorage` default implementation |
| [[`token-state.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/token-state.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/src/token-state.ts) | Token validity classification helpers |

## Summary

- **Configure** the OAuth host via `KIMI_CODE_OAUTH_HOST` for private deployments, or use the default `https://auth.kimi.com`
- **Instantiate** `KimiOAuthToolkit` with optional `homeDir` and custom `fetch` for your environment
- **Authenticate** with `toolkit.login()` using the device-code flow; customize display via `onDeviceCode`
- **Retrieve tokens** through `getCachedAccessToken()` or `tokenProvider().getAccessToken()` for auto-refresh
- **Call APIs** by passing the bearer token in `Authorization` headers; use toolkit helpers for Kimi endpoints
- **Logout** with `toolkit.logout()` to clear credentials from `~/.kimi-code/credentials`

## Frequently Asked Questions

### Does Kimi-Code support OAuth refresh tokens?

Yes. The **OAuthManager** automatically refreshes access tokens using `refreshAccessToken()` in [`oauth.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/oauth.ts) (lines 126-190). The `BearerTokenProvider` calls `ensureFresh()` before every token retrieval, so your code never handles expired tokens manually.

### Can I use Kimi-Code OAuth in browser environments?

Partially. The default `FileTokenStorage` requires Node.js filesystem access. Pass a custom storage implementation and inject a browser-compatible `fetch` via the `KimiOAuthToolkit` constructor options to adapt for non-Node runtimes.

### Where are tokens stored on disk?

By default, in `~/.kimi-code/credentials/` as JSON files with cross-process file locking. Change this path via the `homeDir` constructor option. The storage format and locking mechanism are implemented in [`storage.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/storage.ts) and coordinated through [`oauth-manager.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/oauth-manager.ts).

### What OAuth flows does Kimi-Code support?

The SDK implements the **OAuth 2.0 Device Authorization Grant** (RFC 8628) exclusively. This flow is optimized for CLI tools and devices without browsers. The `requestDeviceAuthorization()` and `pollDeviceToken()` functions in [`oauth.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/oauth.ts) handle the complete flow; no authorization code or PKCE flows are currently implemented.