API keys

An API key is the only credential for calling Amux. A key is the calling identity: anyone holding it can make calls in your name and incur charges, so treat it as you would a password.

Keys are bound to a workspace, and the charges they generate are recorded against that workspace's account.

Creating and viewing#

Create keys on the console's API keys page. Only a name is required; everything else can be changed later.

A key can be viewed in full again on that page after creation — there is no need to regenerate it. A small number of legacy keys issued before retrievable storage shipped keep only a prefix and cannot be shown in full; create a new key if you need one.

Create separate keys per project or per purpose: usage, cost, and logs are all reported per key, and requests made with the same key cannot be attributed separately afterwards.

Status#

Revoke immediately if a key leaks. Revocation only stops subsequent calls; it cannot undo upstream costs already incurred.

Spend limits#

A key can carry four caps; reaching any one of them rejects further calls:

Leave a field empty for no limit on that dimension.

Periods are computed in UTC, independent of the account's or browser's time zone.

Limits count actual charges only. Costs from upstream errors are absorbed by the platform and do not count against your limits.

Caps can be set in three places, and they all apply — whichever runs out first stops the call:

The workspace cap applies to every key in that workspace; its value and the current usage are shown on the usage page.

Callable models#

A key can carry a model allowlist, after which it can call only the models on that list. Leave it empty for no restriction.

Candidate models are shaped both by the layers above and by this key's own supply-tier scope and pinned providers:

• an organization can limit a whole workspace to a list of models, and a key may only narrow further within it;
• once the supply-tier scope or pinned providers are narrowed, models outside their scope no longer appear in the list.

Models already selected that later fall outside the scope are marked "outside current scope" rather than being silently dropped.

Requesting GET /v1/models with a key returns the models that key can actually call; without a key you get the full list. See list models.

Routing#

A key can follow the layer above or be custom. When custom, four settings are available:

Constraint settings can only narrow what the layers above allow (the account, plus the workspace layer in an organization), never widen them. If the workspace has already restricted the scope to "official quality only", a key cannot bring the value tier back into the pool — and that setting is then shown as a fixed value rather than a choice.

"Follow upstream" versus "custom" is not about whether upstream limits apply — they apply either way. The choice decides whether the sorting strategy tracks upstream, whether this key narrows anything further, and whether request-level suffixes are locked.

Pinned and preferred differ in whether they change the candidate pool:

• Pinned providers shrink the pool to the listed providers. Models outside it become uncallable, and the interface shows a coverage hint stating how many of the callable models the current list covers.
• Preferred providers leave the pool unchanged and only adjust order. If every preferred provider is unavailable the request still reaches the others, so this can never make a model uncallable.

The two can be combined, meaning "only A, B, C — and prefer A among them".

Allow request override#

Once a key has its own routing configuration, request-level strategy suffixes are locked by default: a caller using model:@price receives an error rather than having it silently ignored.

Enable "allow request override" in the key's settings to keep per-request flexibility. The typical case is one key serving several workloads, most of them batch (price first) with a particular endpoint needing low latency.

A request suffix can only ever change the sorting strategy; it cannot widen the supply-tier scope or the pinned provider list.

For the full layer-by-layer merge rules, see routing and failover.

Visibility#

Keys record their creator. Within a workspace:

• Workspace admins can see and manage every key in that workspace
• Workspace members can see and manage only the keys they created

Legacy keys without a recorded owner are visible to workspace admins only. See roles and permissions.

Task callback signatures#

Asynchronous generation tasks (/v1/tasks) can call back to an address you provide when the task reaches a terminal state. Anyone who learns that address could forge a "task succeeded" notification, and recipients typically act on it by shipping goods or debiting an account — so Amux signs callback requests and you must verify the signature.

The signing secret is derived per workspace, one per workspace, and is visible to workspace admins on the API keys page. It is a different thing from the API key used for calls, with a different purpose, and the two are not interchangeable.

For the callback payload shape, the Amux-Signature header format, retry backoff, and deduplication requirements, see the POST /v1/tasks documentation in the API reference.

⚠️ When no signing secret is configured the platform does not send callbacks, rather than sending unsigned ones. A callback that fails to send is a visible fault; an unsigned callback is a security hole.

Security recommendations#

• Never put keys in frontend code or commit them to version control. Anyone with the key can call and spend your balance
• Split keys by purpose, so that an incident only requires revoking the affected one
• Set spend limits on production keys to bound the loss from a single incident
• Configure balance alerts so unusual consumption reaches you early; see top-ups and auto top-up
• Review "last used" periodically and revoke keys that have gone unused

Calls and charges arising from a leaked key are the account holder's responsibility; see the terms of service.

Related#

• Routing and failover — how the three configuration layers merge
• Roles and permissions — who can create and manage keys
• Billing overview — how charges arise and are attributed