Authentication
Use API keys to authenticate requests to the Exona API.
API keys
The Exona API uses API keys to authenticate requests. Include your key in the Authorization header of every request:
Requests without a valid key return a 401 Unauthorized error. Requests with a revoked or expired key return a 401 with the error code INVALID_API_KEY.
Key types
Exona issues two types of API key. They use the same endpoint: the key prefix determines which environment your request runs in.
| Type | Prefix | Behaviour |
|---|---|---|
| Live | exo_live_... | Real data, real credits consumed, production results. |
| Test | exo_test_... | Synthetic data, no credits, no external API calls. Use for development and CI. |
Never commit a live key to version control or include it in client-side code. If a live key is compromised, rotate it immediately from the Developers dashboard.
Managing keys
Go to platform.exonalab.com/developers to:
- Create a key: give it a descriptive name (e.g. "Production pipeline", "CI test runner")
- Reveal the key: live keys are shown once at creation and then masked. If you lose a key, create a new one and revoke the old one.
- Rotate a key: generates a new secret while the old one remains valid for a short grace period (24 hours by default) to allow you to update your systems.
- Revoke a key: immediately and permanently invalidates the key.
You can create multiple keys (e.g. one per environment, one per integration partner) and revoke them independently.
Keeping keys secure
Authentication errors
| HTTP status | Error code | Meaning |
|---|---|---|
401 | AUTHENTICATION_REQUIRED | No Authorization header was provided. |
401 | INVALID_API_KEY | The key is malformed, revoked, or does not exist. |
403 | FORBIDDEN_IP | The request IP is not in the key's allowlist. |
All error responses follow the standard error envelope.
Example: rotating a key safely
If you need to rotate a key with zero downtime:
- Create a new key in the Developers dashboard.
- Update your application's secret to the new key and redeploy.
- Verify the new key is working (check the
last_used_attimestamp in the dashboard). - Revoke the old key.
The rotate function (single click in the dashboard) performs steps 1 and 4 automatically with a 24-hour grace period, so the old key remains valid until you have deployed the new one.