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

# Keys & scopes

> qlaud has two key scopes: standard (inference only) and admin (mint + revoke other keys).

Every qlaud key (`qlk_live_…`) has a **scope**:

| Scope            | Can call                                                                                                                       | Notes                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| `standard`       | `/v1/messages`, `/v1/chat/completions`, `/v1/audio/*`, `/v1/images/*`, `/v1/embeddings`, `/v1/videos`, native passthrough URLs | What you give to end-users.              |
| `admin` (master) | Everything `standard` can, **plus** `/v1/keys/*` and `/v1/usage`                                                               | Server-side only. Don't ship to clients. |

## Why two scopes

If a user's key gets stolen, the worst they can do is burn through that
user's spending cap. They can't mint more keys, see other users' usage, or
revoke anything.

Master keys, by contrast, can mint unlimited keys and read all usage. Treat
them like a root password — store in a secret manager, never log, never
expose to client-side code.

## Minting a key

```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
  }'
```

`scope` defaults to `"standard"`. Pass `"admin"` only when you genuinely
need another master key (most apps need exactly one).

## Storing the secret

The full secret (`qlk_live_<64 hex chars>`) is returned **once** on
creation. We store only its SHA-256 hash, indexed for fast lookup.

When you store it on your end, treat it like a password:

* Encrypt at rest if your DB allows
* Don't log it in cleartext
* Don't put it in URL query strings

## Revoking

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

Revocation is **immediate** — we delete the cache entry on revoke, so the
key stops working on the next request, not whenever the 60s cache TTL
expires.

Revoked keys stay in the database for audit (you can still see their
historical usage in `GET /v1/usage`), but they can never be re-enabled.
Mint a new one if the user comes back.

## Listing

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

Returns every key your master account has minted, with `prefix` (safe to
display in dashboards), `scope`, `max_spend_usd`, `created_at`,
`last_used_at`, `revoked`.