Skip to main content
Every qlaud key (qlk_live_…) has a scope:
ScopeCan callNotes
standard/v1/messages, /v1/chat/completions, /v1/audio/*, /v1/images/*, /v1/embeddings, /v1/videos, native passthrough URLsWhat you give to end-users.
admin (master)Everything standard can, plus /v1/keys/* and /v1/usageServer-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

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

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

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.