API keys, spend limits and access levels
A wallet is a prepaid USD balance. The first key (from /v1/keys or the operator) owns the wallet; more keys can draw on it.
| Action | Call | ||
|---|---|---|---|
| List keys (with 30-day requests/spend and current-window spend) | GET /v1/api-keys | ||
| Create a key | POST /v1/api-keys {"name", "limit_usd", "limit_interval", "expires_in", "access"} | ||
| Update name, limit, disable/enable | POST /v1/api-keys/{id} {"name"?, "limit_usd"?, "limit_interval"?, "disabled"?} | ||
| Rotate (old secret stops immediately; name, limit, access, history kept) | POST /v1/api-keys/{id}/rotate (or POST /v1/keys/rotate for the current key) | ||
| Delete (permanent; not the wallet's primary key) | DELETE /v1/api-keys/{id} | ||
| Per-key usage | `GET /v1/api-keys/{id}/usage?days=7 | 30 | 90 → today_usd, this_week_usd, this_month_usd, total_requests, total_cost_usd, by_endpoint, daily` |
Spend limits. limit_usd is a ceiling for one key. limit_interval is daily, weekly (Monday start) or monthly, on UTC calendar windows; omit it for a lifetime limit. limit_interval must be sent with limit_usd; limit_usd: null clears both. Over-limit calls fail with 402 spend_cap_exceeded and are not charged. The wallet balance applies separately.
Expiry. expires_in: 1h, 1d, 7d, 30d, 90d, 180d, 1y, never (default). Fixed at creation. Expired keys get 401.
Access levels. full (everything, including key and billing management), run (run endpoints and read account data; default for new keys), view (read only). Fixed at creation. Out-of-level calls get 403 forbidden.
Disabled keys get 401. Every key change is written to the audit log (GET /v1/audit-log).
Plain Markdown for agents: /docs/api-keys.md · index: llms.txt