Get started
Authentication
Sending the key
Send your key in either header:
Authorization: Bearer ut_live_...x-api-key: ut_live_...Both work on every endpoint. If both are present, Authorization wins. OpenAI clients send the first form and Anthropic clients send the second.
Keys start with ut_live_. A value without that prefix fails with invalid_api_key, and no request at all fails with missing_api_key. Both return 401.
GET /v1/models, GET /v1/models/{id} and GET /v1/workflows/templates work without a key. Everything else needs one.
Projects and keys
An organization has one or more projects. Each key belongs to one project.
- Spend is counted per key and per project, per calendar month (UTC).
- Both a key and its project can have a monthly spend cap. A request is refused when either is reached.
- Credit is held by the organization and shared by all projects.
You need a confirmed email address to create keys. Archiving a project revokes all of its keys.
We store only a hash of each key. The full key is shown once, when you create it. After that the dashboard shows only its prefix (ut_live_ plus six characters).
Scoping a key
Each key can carry four optional limits. Set them in the dashboard when you create or edit the key.
Model allowlist
A list of entries. Each entry is one of:
| Entry | Matches |
|---|---|
utmost/llama-4-scout |
That model id only |
auto |
That alias only. auto does not cover auto-fast or auto-best. |
utmost/qwen3-* |
Any id starting with utmost/qwen3-. A * is allowed only at the end. |
An empty list allows every model your tier can use.
How the allowlist applies:
- Pinned requests. The model id must match an entry, or the request fails with
model_not_allowed(403). - Routed requests where the alias is listed (for example
autois in the list). The router may choose any model. - Routed requests where the alias is not listed. The router chooses only among models that match an entry. If none can serve the request, it fails with
model_not_allowed.
So to confine a key to a set of models while still using the router, list the models and leave the alias out.
Rate limit
Requests per minute for this key, from 1 to 100,000. Without one, the key uses your tier's default. See Rate limits.
Spend cap
A monthly cap in USD for this key. At 50%, 80% and 100% of the cap we send an email and a webhook. Once the cap is reached, requests fail with spend_cap_reached (402) until you raise the cap or the month ends. See Billing.
IP allowlist
A list of IPv4 or IPv6 addresses, or IPv4 CIDR blocks such as 203.0.113.0/24. IPv6 entries must match exactly; IPv6 CIDR blocks are not supported. Requests from other addresses fail with ip_not_allowed (403). The client address is the first entry of X-Forwarded-For, or X-Real-IP when that header is absent.
Rotating a key
There is no in-place rotation. To rotate:
- Create a new key in the same project with the same limits.
- Deploy it.
- Revoke the old key.
Revoked and suspended keys
| State | Error | Meaning |
|---|---|---|
| Revoked | key_revoked (401) |
You revoked it. This is permanent. |
| Suspended | key_suspended (403) |
We suspended it. This happens automatically when a request hits the child-safety hard limit. Contact support. |
| Organization suspended | org_suspended (403) |
Every key in the organization is blocked. Contact support. |
A suspension also sends a key.suspended webhook. See Webhooks.
Batches re-check the key when each request runs. If you revoke a key, its pending batch requests fail.