Skip to content

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 ​

PrefixUse
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 except billing, which must be granted explicitly. A key without billing can'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_ or uf_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 an api_key.leaked webhook naming the key and where it was found.

Errors ​

StatuscodeMeaning
401missing_api_keyNo key in the request
401invalid_api_keyUnknown, expired or revoked key
403scope_missingThe key lacks the scope for this endpoint
403account_suspendedThe organization is suspended