Appearance
Authentication & keys
Every request (except GET /v1/models) needs an API key:
http
Authorization: Bearer uf_live_...x-api-key: uf_live_... also works, so the Anthropic SDK can be used unchanged.
Key types
| Prefix | Use |
|---|---|
uf_live_ | Production traffic |
uf_test_ | Development and CI; labelled separately in usage and logs |
Both are billed. Keys belong to an organization; usage from every key draws on the organization's credit balance.
Scopes and limits
When creating a key in the dashboard you can restrict it:
- Scopes:
chat,embeddings(and reranking),search(and extract/crawl),documents(files and parsing),billing. No scopes selected means every capability exceptbilling, which must be granted explicitly. A key withoutbillingcan't read the balance, buy credits or change billing settings. - Requests per minute and tokens per minute, below your plan's limits.
- Daily spend limit in USD.
- Expiry, 1–365 days.
GET /v1/key returns the calling key's organization, scopes and effective limits.
Keeping keys safe
- Keys are shown once and stored only as a keyed hash; we can't recover a lost key.
- Never ship a key to browsers or mobile apps. Call Usefully from your server.
- Revoking a key in the dashboard takes effect within a few seconds.
- Use one key per service or environment so a leak can be revoked without downtime.
- Leaked keys are revoked automatically. Usefully is a GitHub secret scanning partner: if a
uf_live_oruf_test_key is pushed to a public repository, GitHub reports it to us within minutes, we revoke it, and your organization gets an email and anapi_key.leakedwebhook naming the key and where it was found.
Errors
| Status | code | Meaning |
|---|---|---|
| 401 | missing_api_key | No key in the request |
| 401 | invalid_api_key | Unknown, expired or revoked key |
| 403 | scope_missing | The key lacks the scope for this endpoint |
| 403 | account_suspended | The organization is suspended |