# 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`).
