# auth.md

> How an agent authenticates to the Tunova API. Direct/REST callers and OpenAI Codex use a static
> API key (below). MCP-directory clients (ChatGPT App Directory / Anthropic Connectors) can instead
> use OAuth 2.1 with dynamic client registration — see /.well-known/oauth-protected-resource/mcp.
> Read top to bottom.

## 1. Get an API key
Sign up at https://tunova.ai (50 free tokens, no card), then create a key at https://tunova.ai/keys. Keys look like `sk_live_...`.

## 2. Send it on every request
```http
POST /api/generate HTTP/1.1
Host: api.tunova.ai
X-API-Key: sk_live_...
Content-Type: application/json
```
The MCP `initialize` handshake works without a key; tool calls require it.

## 3. Status codes
- `401` — missing or invalid key.
- `402` — insufficient token balance (top up at https://tunova.ai/billing).
- `403 CLIENT_INACTIVE` — client suspended; terminal until an operator reactivates it.
- `429` — rate limited: **60 requests/min per key** (sliding 60s window). When limiter state is available, rate-checked generation/lyrics accepts and 429 responses carry `RateLimit-Limit`/`RateLimit-Remaining`/`RateLimit-Reset`; reset is a 0–60 second delay, not a timestamp. During fail-open degradation quota headers are omitted. On 429 honor `Retry-After`.
- `503 GENERATION_CAPACITY_UNAVAILABLE` — no generation route is dispatch-ready. No job or token hold was created; honor `Retry-After` and retry with the same idempotency key.

No OAuth, no session cookies — a single API key is the whole auth model. Full spec: https://api.tunova.ai/openapi.json