Authentication
One header on every request.
Authorization: Bearer <your-api-key>That is the whole scheme. There is no X-Api-Key, no signing of outbound
requests, no token exchange and nothing to refresh. The key you are issued is
the key you send, until you revoke it.
POST requests also need Content-Type: application/json.
Getting a key
Issue keys on the API keys page, one mode at a time.
Important
The secret is shown once, when you create it. We store a hash, so we cannot show it to you again and neither can support. If you lose it, revoke it and issue another.
Keep keys out of your repository and out of anything that runs in a browser. Every call to this API is server to server; a key in client-side code is a key anyone can read and spend.
A key is live or test, never both
The two modes are separate credentials against the same base URL.
- A live key sells to real customers and spends your real balance.
- A test key spends play money against reserved numbers.
The key string itself carries no marker, so you cannot tell them apart by
looking. Get account reports mode, and that is
the only place it is stated. Call it once at start-up and refuse to run if the
mode is not the one you expected. It is a cheap check that prevents an
expensive mistake.
A key that somehow carries both modes is refused outright rather than guessed
at, with 403 and "This key carries both test and live access. Ask us to
reissue it for one mode."
What a live key additionally needs
| Requirement | Live | Test |
|---|---|---|
| The key exists and is not revoked | yes | yes |
| Your account is enabled | yes | yes |
| KYB approved | yes | no |
| Calling address on your allowlist | yes, when you set one | no |
The allowlist is on your account and takes plain addresses and CIDR ranges. An
empty allowlist means we accept your live key from anywhere, which is a
reasonable place to start and a poor place to stay. calling_from on
Get account reports the address we saw, so you
do not have to guess what to add.
When authentication fails
| Status | Meaning |
|---|---|
401 | No key, a malformed header, or a key that no longer exists. |
403 | The key is real but may not do this. |
A 403 has three separate causes and only the message tells them apart:
This token cannot use the reseller API.The token is not a partner key, or your account is not enabled or not KYB approved.This address is not on your allowlist.Add it, or call from somewhere you have allowlisted.This key carries both test and live access. Ask us to reissue it for one mode.
Note
Retrying a 401 or a 403 with the same key will not start working. Both
mean something needs changing on your side or ours.