REST API
Authentication
Send the key in every call:
Authorization: Bearer <your API key>
The guides write the key as $ESOPPARI_KEY: keep it in an environment
variable or a secret store of your server, never in code.
Keys
- An administrator creates and revokes keys in the admin portal, under API keys. An organisation can have 10 active keys.
- The portal shows a key once. The service stores only a hash of it, so a lost key cannot be shown again: revoke it and create a new one.
- A key starts with
esk_live_and ends with a checksum, so secret scanners such as GitHub secret scanning can find a key that leaked into a repository. - A key can have an expiry date. It stops working at the end of that day, in UTC.
Scope
A key acts for your organisation: see What a key can do.
Rotate a key
- Create a second key.
- Deploy it to your system.
- Revoke the first key. It stops working on the next call.
Answers
| Status | code |
Meaning |
|---|---|---|
| 401 | missing_api_key |
The call has no Authorization: Bearer header. |
| 401 | invalid_api_key |
The key is unknown, wrong, revoked or expired. The answer does not say which. |
| 403 | tenant_suspended |
Your organisation is suspended or closed. |
Keep the key safe
- Keep the key on your server. Never put it in a browser, a mobile app or a repository.
- Use one key for each system, so you can revoke one without the others.
- The audit log of your organisation names the key (
KEY-...) for every action it took.