---
name: kimi-auth-pattern
title: Kimi/Moonshot API Authentication Pattern
description: Correct configuration for Kimi Code API keys vs legacy Moonshot keys. Critical for preventing auth failures when setting up Hermes agents.
trigger: When configuring kimi-coding provider, setting KIMI_API_KEY, or troubleshooting Kimi auth errors.
---

# Kimi/Moonshot Authentication Pattern

## The Special Way

Kimi has **two different API endpoints** depending on your key type:

### 1. Kimi Code Keys (platform.kimi.ai)
- **Key format:** `sk-kimi-xxxxxxxx`
- **Base URL:** `https://api.kimi.com/coding/v1`
- **Source:** platform.kimi.ai (newer Kimi Code platform)

### 2. Legacy Moonshot Keys (platform.moonshot.ai)
- **Key format:** `sk-xxxxxxxx` (no `kimi` prefix)
- **Base URL:** `https://api.moonshot.ai/v1`
- **Source:** platform.moonshot.ai (legacy)

## Critical Rule

**DO NOT manually set `KIMI_BASE_URL` unless you know exactly which key type you have.**

The Hermes auto-detection logic in `auth.py` handles this:
```python
def _resolve_kimi_base_url(api_key, default_url, env_override):
    if env_override:
        return env_override  # User override wins
    if api_key.startswith("sk-kimi-"):
        return "https://api.kimi.com/coding/v1"
    return default_url  # "https://api.moonshot.ai/v1"
```

## Common Failure Mode

**What breaks Ezra:**
1. Ezra has a `sk-kimi-*` key
2. I manually set `KIMI_BASE_URL=https://api.moonshot.ai/v1`
3. Auth fails because key and endpoint mismatch

**Correct setup:**
```yaml
providers:
  kimi-coding:
    timeout: 60
    # NO base_url set - let auto-detection work
    # Just set KIMI_API_KEY env var
```

## Environment Variables

- `KIMI_API_KEY` - The API key (required)
- `KIMI_BASE_URL` - Override base URL (optional, usually wrong to set)

## Verification

Check which endpoint a key needs:
```bash
# If key starts with sk-kimi-
KIMI_BASE_URL=https://api.kimi.com/coding/v1

# Otherwise
# (leave unset, defaults to api.moonshot.ai/v1)
```

## Related Code

- `hermes_cli/auth.py`: `_resolve_kimi_base_url()`
- `hermes_cli/auth.py`: `KIMI_CODE_BASE_URL` constant