Authentication
Every API request carries a key in the Authorization header. Keys are bearer secrets that belong to one account and one environment, so treat them like a password: keep them in a secret store, never in source control, and never in a browser.
Authorization: Bearer esf_sk_live_v1_<key id>_<secret>Key format
A key is created as two strings.
| Example | Use | |
|---|---|---|
| Secret | esf_sk_live_v1_7fQ2mR8xKp_… | The bearer token. Shown once, at creation. |
| Key id | esf_k_live_7fQ2mR8xKp | The public identifier. Safe to log, display and quote to support. |
live keys work on production and test keys on staging. v1 is the key format version, not the API version.
Header only
Send the key in the Authorization header and nowhere else. A key in a query string would end up in logs and browser history, so the API does not accept it there.
If you use the SDK, pass apiKey to the client. The CLI reads ESFERA_API_KEY or the key it stored at login.
Rotate a key
You can hold up to five active keys, so rotation never needs downtime.
- Create a new key on your account page.
- Deploy it to the service that uses the old one.
- Check the old key's last-used time on the page. When it stops moving, revoke it.
Revoke a key
Revoke a key from the same page. A revoked key stops working within 10 seconds, and a request made with it is answered 401 with invalid-api-key. If a secret leaks, revoke it first and create its replacement after.
When authentication fails
The API gives one answer for every kind of key failure, so it never reveals whether a key id exists. A request is refused with invalid-api-key when the key is missing, malformed, unknown, revoked, expired, or for the other environment. Check the header, then which host you are calling: a live key sent to staging, or a test key sent to production, is refused.
The full contract is in the reference.