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 auto is 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:

  1. Create a new key in the same project with the same limits.
  2. Deploy it.
  3. 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.