Managing keys

A management key (mux-mgmt-...) can create and administer API keys. Use it to issue one key per customer or agent, each with its own spend cap, and to turn keys off instantly. Management keys can't run searches. See Authentication for the difference between key types.

All endpoints on this page require a management key and return 403 wrong_key_type for an API key, except GET /v1/key, which works with either.

import { Mux } from "getmux";

const admin = new Mux({ apiKey: process.env.MUX_MGMT_KEY });

The key object

{
  "id": "key_Hx2mQp9aLwT4kZ1v",
  "name": "customer-acme",
  "label": "mux-AbCdE…",
  "type": "api",
  "limit": 25.0,
  "limit_remaining": 18.4,
  "limit_reset": "monthly",
  "disabled": false,
  "expires_at": "2027-01-01T00:00:00Z",
  "usage": 6.6,
  "usage_period": 6.6,
  "created_at": "2026-10-12T17:00:00Z",
  "updated_at": "2026-10-12T17:00:00Z"
}

Field	Description
`id`	Key id (`key_...`). Use this in the other endpoints. It is not the secret.
`name`	Display name, or `null`.
`label`	Masked prefix of the secret. The full secret is only ever returned once, on creation.
`type`	`api` or `management`.
`limit`	Credit limit in USD, or `null` for unlimited.
`limit_remaining`	What is left of the limit in the current window, or `null` if unlimited.
`limit_reset`	`daily`, `weekly`, `monthly`, or `null` (the limit never resets).
`disabled`	`true` if the key is switched off.
`expires_at`	RFC 3339 timestamp (UTC), or `null`.
`usage`	Lifetime spend of this key in USD.
`usage_period`	Spend in the current limit window.
`created_at`, `updated_at`	RFC 3339 timestamps (UTC).

Create a key

POST /v1/keys

Field	Type	Description
`name`	string	1 to 100 characters. Optional.
`limit`	number	Credit limit in USD, 0 to 1,000,000. Omit for unlimited. A limit of `0` creates a key that can't spend.
`limit_reset`	string	`daily`, `weekly` or `monthly`. Optional.
`expires_at`	string	RFC 3339 timestamp in the future, for example `2027-01-01T00:00:00Z`. Optional.

The response is 201 with the secret and the key object. This is the only time the secret is returned.

curl https://api.getmux.io/v1/keys \
  -H "Authorization: Bearer $MUX_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer-acme", "limit": 25, "limit_reset": "monthly"}'

Unknown fields return 400 invalid_request.

List keys

GET /v1/keys?offset=0&limit=100

Returns your API keys (not management keys), newest first. limit is 1 to 100 (default 100); offset defaults to 0.

curl "https://api.getmux.io/v1/keys?limit=20" \
  -H "Authorization: Bearer $MUX_MGMT_KEY"

Get a key

GET /v1/keys/{id}

curl https://api.getmux.io/v1/keys/key_Hx2mQp9aLwT4kZ1v \
  -H "Authorization: Bearer $MUX_MGMT_KEY"

Returns { "data": { ...key object } }, or 404 not_found. You can only see keys in your own account.

Update a key

PATCH /v1/keys/{id}

Send only the fields you want to change. Fields you leave out are unchanged; sending null clears a field.

Field	Type	Description
`name`	string or null	New name (1 to 100 characters), or `null` to clear it.
`limit`	number or null	New limit in USD, or `null` to remove the limit.
`limit_reset`	string or null	`daily`, `weekly`, `monthly`, or `null`.
`disabled`	boolean	`true` switches the key off; `false` switches it back on.

Expiry can only be set when a key is created.

# raise the limit
curl -X PATCH https://api.getmux.io/v1/keys/key_Hx2mQp9aLwT4kZ1v \
  -H "Authorization: Bearer $MUX_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50}'

Lowering a limit below what the key has already spent in the current window doesn't refund anything; the key is simply blocked until the window resets.

Delete a key

DELETE /v1/keys/{id}

Permanently stops the key from working. Returns { "deleted": true }, or 404 not_found if it doesn't exist. Its past usage still counts toward your totals.

curl -X DELETE https://api.getmux.io/v1/keys/key_Hx2mQp9aLwT4kZ1v \
  -H "Authorization: Bearer $MUX_MGMT_KEY"

Inspect the current key

GET /v1/key

Returns the key object for the key that made the call. Works with API keys and management keys. This is how an agent can check its own remaining budget before starting expensive work.

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

How limits work

Limits are in USD and count what the key spends on searches. They apply to the credit price of requests made with that key.
Reset windows are in UTC: daily resets at 00:00 UTC every day, weekly at 00:00 UTC on Monday, and monthly at 00:00 UTC on the 1st. With no limit_reset, the limit is a lifetime cap.
They are enforced exactly. The limit check and the balance check happen together, so a burst of concurrent requests can't push a key past its limit.
A blocked request is free. If a request would exceed the limit, it is rejected with 402 key_limit_exceeded and nothing is charged. When you use models fallbacks, a model that doesn't fit under the limit is skipped and a cheaper one later in the list can still run.
Failed calls give the budget back. If a provider call fails and is refunded, the amount is also returned to the key's limit.
BYOK fees are charged to your credits but aren't counted against a key's limit. See Bring your own keys.

Situation	Response
Request would exceed the key's limit	`402 key_limit_exceeded`
Key is disabled	`401 key_disabled`
Key is past `expires_at`	`401 key_expired`

Note: A change to a key can take up to about 15 seconds to take effect on every server. Disabling or deleting a key takes effect immediately for requests handled by the server that processed the change.

Example: one key per customer with a monthly cap

Give each of your customers their own key, capped at $25 a month and expiring in a year. If a customer's agent goes into a loop, it stops at $25 and doesn't touch your other customers.

curl https://api.getmux.io/v1/keys \
  -H "Authorization: Bearer $MUX_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-acme",
    "limit": 25,
    "limit_reset": "monthly",
    "expires_at": "2027-10-12T00:00:00Z"
  }'