Keys, scopes and headers

The public API authenticates with a single header and nothing else. It has no anonymous endpoints: every operation in the spec requires a key, and almost every one names a specific scope in its own description. The exception is the AI model catalog: any active key works for it. There is one fewer reference page than there are operations: PUT and PATCH /templates/{template} are collapsed into one (it's a single operation under two methods), and POST /broadcasting/auth is explained in the Realtime section.

X-API-KEY: <your key>

A separate surface, not a second way to sign in

The public surface (/api/public/*) and the dashboard API are different surfaces with different authentication. The dashboard Bearer token doesn't work here; conversely, a key doesn't open dashboard endpoints. The header is called exactly X-API-KEY — neither Authorization nor Api-Key is recognized, and both get the same response as a missing key.

The key is hashed (sha256) and resolved with a cache of about an hour. The practical consequence: editing a key's scopes or deactivating it in the dashboard doesn't take effect instantly — requests may keep going through on the old state for a while.

Eleven scopes and a wildcard

The scope is checked before any business logic: a key without the required scope gets 403 and nothing is executed. The “Operations” column shows how many public API endpoints the scope opens (reference pages plus POST /broadcasting/auth).

The two AI model catalog operations (GET /ai/models and GET /ai/models/{key}) require no scope at all — they're not in the table.

Three presets

When you create a key, its scopes are usually picked with a preset.

The wildcard * is a separate value, not a synonym for the full preset: it also passes checks that didn't exist when the key was issued (but not the reseller scopes). Which of the two ways to “grant everything” the dashboard applies when you pick full isn't specified by the sources — if it matters, check the scope list of the already created key in the dashboard.

The automation trap

The preset named “for automation” doesn't include templates.write — only templates.read. This isn't a documentation typo or a bug: that's how it's designed. By the same logic it also lacks voices.write: for a key that clones voices, this scope is added manually, or you take full.

The consequence is concrete. For TTS, the voice is set not by an order field but by the template's config.tts_settings.voice_id — so the canonical scenario starts with POST /templates. With an automation key it stops at the very first step: 403, and the order is never created.

If the template was created in advance (on the web or with another key), automation is enough: the template's owner is the account, not a specific key. Someone else's template, however, won't open with any key.

Language and timezone headers

Both headers are optional, and neither is declared as a parameter in the OpenAPI — a client generated from the spec won't know about them, so you'll have to send them manually.

• X-Locale — the language of human-readable strings: message in responses and names in reference lists such as GET /voices/tags. It has no effect whatsoever on machine fields (reason, statuses, codes), and that's exactly why you must not branch on message. The sources disagree: the OpenAPI names this header in 79 descriptions and never mentions Accept-Language, while the LLM reference does the opposite; if the response language is critical, check the actual behavior with your own key and send both headers.
• X-Timezone — an IANA zone name (Europe/Moscow). Points in time in responses arrive in ISO-8601 with an explicit offset, UTC by default. A bare offset (+03:00) is rejected: it doesn't know about daylight saving time. The server returns the zone it actually applied in the same header — send garbage and you'll see X-Timezone: UTC in the response.

What a key can't do

The public surface doesn't process payments and doesn't manage itself. With a key you cannot: top up the balance, make transfers, buy subscriptions, change the profile, or manage the API keys themselves. All of that stays in the dashboard. Separately: orders have no update/delete — only cancel and retry, and PUT/PATCH/DELETE /orders/{order} will answer 405/404.

Key smoke test

The cheapest check is the profile: one operation, one scope, no side effects.

curl -s -o /dev/null -w '%{http_code}\n' \
  'https://api.lumean.app/api/public/user' \
  -H 'X-API-KEY: <your key>'

The key nuance is the second row: 403 confirms that the key is alive. If your key lacks profile.read by design, check GET /orders?per_page=1 instead — it needs only orders.read.

Keys are created in the Developers section, which also shows the active scopes and limits of each key. Don't have a key yet? Sign up first — keys are issued only to the account owner.