> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlaud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# /v1/keys

> Mint, list, and revoke API keys programmatically. Requires master (admin) scope.

Programmatic API key management. Requires a master (admin-scoped) qlaud key
on the `x-api-key` header.

## POST /v1/keys — Mint

```bash theme={null}
curl https://api.qlaud.ai/v1/keys \
  -H "x-api-key: $QLAUD_MASTER_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "user_42",
    "scope": "standard",
    "max_spend_usd": 5
  }'
```

### Body

| Field           | Type                    | Required | Default            | Description                                           |
| --------------- | ----------------------- | -------- | ------------------ | ----------------------------------------------------- |
| `name`          | string                  | yes      | —                  | Display label. Surfaced in `/v1/usage` as `key_name`. |
| `scope`         | `"standard" \| "admin"` | no       | `"standard"`       | `admin` keys can call `/v1/keys/*` and `/v1/usage`.   |
| `max_spend_usd` | number                  | no       | `null` (unlimited) | Lifetime cap in USD. Enforced gateway-side.           |

### Response (201)

```json theme={null}
{
  "id": "0e2c3a91-7f10-4d83-9b22-6c41a8ee83d9",
  "name": "user_42",
  "secret": "qlk_live_a1b2c3...wxyz",
  "prefix": "qlk_live_a1b2…wxyz",
  "scope": "standard",
  "max_spend_usd": 5
}
```

<Warning>
  `secret` is returned **once**. We store only its SHA-256 hash. If you lose
  it, revoke + remint.
</Warning>

## GET /v1/keys — List

```bash theme={null}
curl https://api.qlaud.ai/v1/keys -H "x-api-key: $QLAUD_MASTER_KEY"
```

### Response

```json theme={null}
{
  "keys": [
    {
      "id": "0e2c3a91-...",
      "name": "user_42",
      "prefix": "qlk_live_a1b2…wxyz",
      "scope": "standard",
      "max_spend_usd": 5,
      "created_at": 1746124800000,
      "last_used_at": 1746518400000,
      "revoked": false
    },
    ...
  ]
}
```

## DELETE /v1/keys/:keyId — Revoke

```bash theme={null}
curl -X DELETE https://api.qlaud.ai/v1/keys/<key_id> \
  -H "x-api-key: $QLAUD_MASTER_KEY"
```

### Response (200)

```json theme={null}
{ "ok": true }
```

Revocation is **immediate** — KV cache entry is deleted on revoke, so the
key stops working on the next request.