Authentication
// secret keys, sent as a bearer token
Authenticate every request with your secret API key in the Authorization header. Keys are created and rotated from your dashboard. Live keys are prefixed sk_live_ and solve real gates against your balance. Test keys sk_test_ run against a sandbox that returns a deterministic, never-billed token stamped "mode":"sandbox" — ideal for wiring up and CI, but they never clear a real gate, so don't ship them to production.
Authorization: Bearer sk_live_8Kd2aF9pQ…X1c
// keep secret keys server-side — never ship them to a browserTreat keys like passwords. A leaked sk_live key can spend your balance — rotate it from the dashboard the moment it's exposed, and the old key dies instantly.
Four different refusals, and only one of them is the key being wrong. They are easy to confuse because all four arrive on a request that looks identical:
| Status | error.code | What it actually means |
|---|---|---|
| 401 | invalid_key | Missing, malformed, or revoked. A rotated key returns this immediately — there is no grace period by design. |
| 403 | email_unverified | The key is real and the account has not verified its email. Live keys only; sandbox keys work regardless. |
| 402 | key_budget_exceeded | The key is fine and its own monthly budget is spent. The workspace may still have balance. |
| 429 | rate_limited | The key is fine and it is going too fast. Never billed. Back off for the window in Retry-After. |
Keys are a blast radius, not just credentials. Each one can carry its own rate limit and its own monthly budget, set independently of the workspace's, so the key in a CI job or a third-party integration can be capped at what that job should ever need. A key that leaks then costs you its budget rather than your balance. Both limits live under Settings → Usage & limits alongside live utilisation.
Sandbox keys are not a lesser live key. An sk_test_ key returns a deterministic response stamped "mode":"sandbox" instantly, at no cost and against no real gate. That makes it right for wiring up the call and for CI, and useless for anything that has to clear an actual challenge — the token it returns will not be accepted by Cloudflare. Check mode in the response before trusting a token in production; it is there so a test key in a production config fails loudly instead of quietly.
Ready to pour through the gate?
// free sandbox keys · no card required to start