Skip to content
Theme
Upload a photo Upload
Theme
Theme
Upload a photo

Developers

Authentication and API keys

Live and test keys, the key format, scopes, IP allowlists, per-key limits, rolling and revoking keys.

On this page
  1. Live and test keys
  2. Rules for sending keys
  3. Scopes
  4. Create a key
  5. IP allowlist
  6. Per-key limits
  7. Roll a key
  8. Revoke a key
  9. Request log

Every API request is authenticated with an API key in the Authorization header. There are no sessions or cookies.

curl
curl https://studio-api.mutexai.net/v1/balance \
  -H "Authorization: Bearer mx_live_Ab3dEf12_9xQ2LmT7vR4kW8pZ1cN6bY3hJ5sD0fG2"

Live and test keys#

KeyStarts withUses
Livemx_live_Your real balance. Needs a verified email.
Testmx_test_A separate sandbox wallet and simulated outputs. See Sandbox.

A key looks like mx_live_Ab3dEf12_9xQ2LmT7vR4kW8pZ1cN6bY3hJ5sD0fG2: the mode, an 8-character public ID, and a 32-character secret. We store only a keyed hash of the secret, so we can never show a key again. After you create it, the dashboard shows only its start, like mx_live_Ab3dEf12_….

Rules for sending keys#

  • Send it as Authorization: Bearer <key>.
  • Never put a key in a URL. A request with a key in the query string is refused with 400 api_key_in_query, because URLs end up in logs.
  • Use keys only on your server. Never ship a key in a website, a mobile app or a browser extension.
  • Use one key per app or server, so you can revoke one without breaking the others.

Scopes#

Each key can only do what its scopes allow. A missing scope returns 403 insufficient_scope with the missing scope in required_scope. Give each key only the scopes it needs.

ScopeAllowsOn new keys
sets:read Read sets (its endpoints are coming soon) Yes
sets:write Make sets (its endpoints are coming soon) Yes
backgrounds:write Background tools (its endpoints are coming soon) Yes
logos:write Logo studio (its endpoints are coming soon) No
uploads:write Uploads (its endpoints are coming soon) Yes
balance:read Read balance Yes
ledger:read Read ledger No
webhooks:manage Manage webhooks No

Create a key#

  1. Open Developers → API keys and choose Create key.
  2. Give it a name, choose Live or Test, and tick its scopes.
  3. Optional: under IP allowlist and limits, add allowed IPs, a requests-per-minute limit and a monthly credit cap.
  4. Copy the key from the screen that follows. It is shown once.

Keys are managed in the dashboard only. There is no API endpoint that creates keys.

IP allowlist#

An allowlist limits a key to your servers. Enter IP addresses or CIDR ranges, one per line, for example 203.0.113.10 or 198.51.100.0/24. IPv6 works too. A request from any other address gets 403 ip_not_allowed. Leave it empty to allow any address.

Per-key limits#

  • Requests per minute: a lower limit for this key. It can never be higher than your plan's limit. See Rate limits.
  • Monthly credit cap: the most credits this key may spend in a calendar month. Over the cap, spending requests get 402 credit_cap_reached. Use it to protect your balance from a bug or a leaked key. The cap counts from the 1st of each month (UTC) and applies to the spending endpoints that are coming soon.

Roll a key#

Rolling makes a new key with the same name, scopes, allowlist and limits, and lets the old key keep working for a while so you can deploy the new one without downtime.

  1. On the key, choose Roll.
  2. Choose how long the old key keeps working: from 0 hours (stop now) up to 7 days. The default is 24 hours.
  3. Copy the new key, deploy it, and the old one expires on its own.

Roll keys on a schedule, and whenever someone with access leaves your team.

Revoke a key#

Revoking stops a key at once. To confirm, type the key's name. We email the account's verified users and send an api_key.revoked webhook. A revoked key cannot be restored: create a new one.

Request log#

Developers → Logs shows the last 100 requests for each key: method, path, status, time taken, credits and the error code. We keep request logs for 30 days. We never log request bodies or headers.

Still stuck? Email [email protected] with what you tried and, for API problems, the request_id.

Type at least 2 letters. Use the arrow keys to move and Enter to open.

    Type at least 2 letters. Use the arrow keys to move and Enter to open.