73 lines
2.1 KiB
Markdown
73 lines
2.1 KiB
Markdown
|
---
|
||
|
|
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
|