Authentication

One header on every request.

Every requesthttp
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

RequirementLiveTest
The key exists and is not revokedyesyes
Your account is enabledyesyes
KYB approvedyesno
Calling address on your allowlistyes, when you set oneno

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

StatusMeaning
401No key, a malformed header, or a key that no longer exists.
403The 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.