Authentication

Every request is authenticated with a bearer token in the Authorization header:

curl https://api.getmux.io/v1/credits \
  -H "Authorization: Bearer $MUX_API_KEY"

The token must start with mux-. A missing, malformed or unknown token returns 401 invalid_api_key.

Two endpoints are public and need no key: GET /v1/models and GET /v1/credits/pricing.

Two kinds of key

	API key	Management key
Prefix	`mux-`	`mux-mgmt-`
Can call `POST /v1/search`	Yes	No
Can create, edit and delete API keys	No	Yes
Can manage provider keys	No	Yes
Can read credits, usage and its own key (`GET /v1/key`)	Yes	Yes

Use an API key in your application or agent. Use a management key in the tooling that issues keys to your customers or agents. Keeping the two separate means a leaked search key can't be used to mint new keys or change billing settings, and a management key can't be used to run up search costs.

Calling an endpoint with the wrong kind of key returns 403 wrong_key_type:

{
  "error": {
    "code": "wrong_key_type",
    "message": "Management keys can't make search calls. Use an API key."
  }
}

Both kinds of key belong to your account and draw on the same credit balance.

Creating keys

API keys are created in the dashboard under API keys, or programmatically with a management key through POST /v1/keys. Management keys (mux-mgmt-...) are created from the same page of the dashboard.

A key's secret is shown exactly once, when it is created. Mux stores only a SHA-256 hash of it, so we can't show it to you again. If you lose it, create a new key and delete the old one. In listings you'll only see a masked label like mux-AbCdE….

Per-key limits, disabling and expiry

Each API key can have its own:

Credit limit in USD, optionally resetting daily, weekly or monthly.
Expiry time, after which the key stops working.
Disabled switch, which turns a key off immediately without deleting it.

These are enforced on the server. A request that would exceed a key's limit is rejected with 402 key_limit_exceeded and costs nothing. A disabled key returns 401 key_disabled, and an expired key returns 401 key_expired. See Keys for details.

Note: Changes you make to a key (disabling it, deleting it, changing a limit) apply right away on the server that handles your request and can take up to about 15 seconds to propagate across all servers.

Keeping keys safe

Use environment variables. Don't commit keys to source control or ship them in browser or mobile code. The SDKs read MUX_API_KEY automatically.
Issue one key per agent, service or customer. Per-key usage is visible in the dashboard, and one compromised key can be deleted without disturbing the rest.
Set a credit limit on every key. A runaway loop in an agent is the usual way a balance gets drained. A limit caps the damage to that key.
Set an expiry on keys you hand to short-lived jobs or external users.
Rotate by replacing. Create the new key, deploy it, then delete the old one.
Delete leaked keys immediately from the dashboard or with DELETE /v1/keys/{id}.