Keys and authentication
Only GET /v1/models is public — every generating endpoint needs a key in the header:
Authorization: Bearer mxn-...Issuing a key
Section titled “Issuing a key”Account → Profile → API keys → “Create key”.
The full key is shown once, right after creation. We store only a sha256 hash, the prefix and the last few characters — a key cannot be recovered, so replace a lost one rather than hunting for it.
Scopes
Section titled “Scopes”A key can be limited to a set of capabilities. There are seven:
| Scope | What it unlocks |
|---|---|
chat |
POST /chat/completions |
search |
Web-search models inside /chat/completions |
images |
POST /images/generations, POST /images/edits |
video |
All /videos endpoints |
music |
All /audio/music endpoints |
audio |
POST /audio/speech, POST /audio/transcriptions |
embeddings |
POST /embeddings |
A key with every scope selected reaches the whole catalog. A request outside the allowed scopes returns 403. GET /balance is not on the list: any working key can read the balance — otherwise a narrowly scoped key could not check what it can afford.
Scope each key to its job: a key that sits in a browser extension and can only do chat will not burn your balance on video if it leaks.
Allowed models and daily limit
Section titled “Allowed models and daily limit”Two per-key settings are finer than scopes — set them at creation and change them in the dashboard at any time:
| Setting | What it does |
|---|---|
| Allowed models | A list of ids from the catalog (GET /models). A request with any other model gets 403 with code model_not_allowed. Empty — any model within the scopes |
| Daily limit, ₽ | A cap on charges made with this key per calendar day (UTC). Once successful charges since midnight reach the limit — 429 with code daily_limit_exceeded and an X-Mixen-Daily-Reset header (reset time). The account balance and other keys are unaffected |
While the limit is not exhausted, every response carries X-Mixen-Daily-Limit, X-Mixen-Daily-Spent, X-Mixen-Daily-Reset — track the budget without extra requests. The check runs before the request and the price is known only afterwards, so the last request of the day may slightly exceed the limit.
A sensible setup for an unattended integration: one scope, one or two models, a daily limit — a leaked key can at worst spend the day’s budget, not the balance.
Storage
Section titled “Storage”The key is access to your balance. Treat it like any payment secret:
- environment variables or a secret manager, never the repository;
- never in client-side code — the browser and mobile apps hand the key to anyone who opens DevTools;
- one key per application and environment, so revoking one does not take down the rest;
- if you suspect a leak, delete the key in your account — that takes effect immediately.
Checking a key
Section titled “Checking a key”The cheapest check is the balance: it spends no tokens and works regardless of the key’s scopes.
curl https://api.mixen.ai/v1/balance \ -H "Authorization: Bearer $MIXEN_API_KEY"{"balance_rub": "123.46", "currency": "RUB"}balance_rub is a string with two decimals: parse it as a decimal, not a float, so cents do not drift. The balance is shared by the bot, the cabinet and the API.
A generating request for a full picture:
curl https://api.mixen.ai/v1/chat/completions \ -H "Authorization: Bearer $MIXEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-5.6-luna","messages":[{"role":"user","content":"ping"}],"max_tokens":5}'A 401 means the key is missing or revoked. A 402 means the key works but the balance is too low.