Authentication
Every request, except the OpenAPI document, carries your API key as a bearer token. Keys are secrets: they are shown once when created, and Esfera stores only a hash of them.
Authorization: Bearer esf_sk_{live|test}_v1_… — the secret shown once at key creation. Header only, never a query string. The loggable key id is the esf_k_… prefix. Live keys work on production, test keys on staging; a key presented to the other host is refused. A revoked key stops working within 10 seconds.
The header
Authorization: Bearer esf_sk_live_v1_<key id>_<secret>The key goes in the Authorization header and nowhere else. A key in a query string ends up in server logs, proxies and browser history, so the API does not read it from there.
Key format
| Part | Example | Use |
|---|---|---|
| Secret | esf_sk_live_v1_7fQ2mR8xKp_… | The bearer token. Shown once. Keep it in a secret store. |
| Key id | esf_k_live_7fQ2mR8xKp | The public, permanent identifier. Safe to log, display and quote to support. |
The secret embeds its own key id, so a failed request is still attributable to a key without revealing anything usable. live and test mark the environment, and v1 is the key format version.
Environments
A live key works on https://api.esfera.audio and a test key on https://staging-api.esfera.audio. A key presented to the other host is refused as invalid-api-key, so a misconfigured environment fails loudly instead of converting against the wrong account.
Failure
A request with a missing, malformed, unknown, revoked or expired key is answered 401 with invalid-api-key. The response never says which of those it was, so a prober learns nothing about which key ids exist. Check the header, then which host you are calling.
Revocation
A revoked key stops working within 10 seconds. The API caches successful key lookups for that long so that a burst of requests does not cost a database round trip each, and 10 seconds is the longest a revoked key can still be accepted.