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
Every API request is authenticated with an API key in the Authorization header. There are no sessions or cookies.
curl https://studio-api.mutexai.net/v1/balance \
-H "Authorization: Bearer mx_live_Ab3dEf12_9xQ2LmT7vR4kW8pZ1cN6bY3hJ5sD0fG2"
Live and test keys#
| Key | Starts with | Uses |
|---|---|---|
| Live | mx_live_ | Your real balance. Needs a verified email. |
| Test | mx_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.
| Scope | Allows | On 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#
- Open Developers → API keys and choose Create key.
- Give it a name, choose Live or Test, and tick its scopes.
- Optional: under IP allowlist and limits, add allowed IPs, a requests-per-minute limit and a monthly credit cap.
- 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.
- On the key, choose Roll.
- Choose how long the old key keeps working: from 0 hours (stop now) up to 7 days. The default is 24 hours.
- 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.