allegro-checkpoint/skills/infrastructure/kimi-auth-pattern/SKILL.md

name, title, description, trigger

name	title	description	trigger
kimi-auth-pattern	Kimi/Moonshot API Authentication Pattern	Correct configuration for Kimi Code API keys vs legacy Moonshot keys. Critical for preventing auth failures when setting up Hermes agents.	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:

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:

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:

# 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