Authentication
Creating, using, rotating and revoking API keys.
Every request carries a key in the standard bearer header:
Authorization: Bearer $ETERIAL_API_KEYKeys are created in the dashboard. The full value is shown once, at creation, and is not recoverable afterwards — we store only a hash of it.
What a key looks like
A key begins with zl_live_, followed by a public identifier and the secret
itself. The leading part — the prefix plus the identifier — is not secret: it is
the label shown next to the key in the dashboard, and it is what appears against
each request in the usage log. That is how you tell which key spent what.
The secret after it is the part that must never leave your server.
Expiry, rotation, revocation
A key can be given an expiry when you create it, or left without one. An expired
or revoked key stops working immediately and its requests return 401.
To rotate without downtime: create the new key, deploy it, then revoke the old one. Both work in parallel until you remove the old one, so there is no window where neither is valid.
Keys belong on servers
Anything in a browser bundle, a mobile app or a public repository is compromised the moment it ships. Calls from a client should go through your own backend, which holds the key.
Errors
| Status | code | Meaning |
|---|---|---|
401 | missing_api_key | No Authorization header was sent. |
401 | invalid_api_key | The key is unknown, expired or revoked. |
403 | — | The key is valid but the account is suspended. |
One key per environment
Keys are the only dimension the usage log attributes spend to, so separate keys for production, staging and each developer are what make the numbers readable later. Revoking one then costs nothing elsewhere.