How do I create, use and protect my API keys?

An API key identifies your application to our API. Anyone who has a live key and can call from a whitelisted address can spend your wallet, so keys deserve the same care as a bank password.

Test keys and live keys

  • Test keys use the sandbox. They are free, never touch your wallet and can be created as soon as you have requested API access.
  • Live keys move real money. They can be created after your API account is approved and a package is active.

The keys page marks each key as *Test* or *Live* and shows when it was last used.

Create a key

  1. Open My services › API services and go to the keys page.
  2. Under Create a key, enter a name that tells you where the key is used: "Production server", "Staging", "Billing job".
  3. Choose test or live.
  4. Choose an expiry: never, or after 30, 90, 180 days or a year. An expiry is a good idea for keys given to a contractor or used for a short project.
  5. Press Create key.

The page then shows two values, once:

  • the API key, which you send with every request in the X-Api-Key header;
  • the signing secret, which you use to sign requests and which never leaves your server.

Copy both immediately. We store only a fingerprint of them and cannot show them again.

One key per place

Create a separate key for each server or application. When one of them is retired or compromised, you revoke only its key and everything else keeps running. The "last used" column also tells you which keys are still in use.

Sign your requests

A signature proves that a request really comes from you and was not changed on the way. You calculate it from the request and your signing secret and send it in the X-Signature header. The API documentation gives the exact recipe with code examples.

Under Security and webhooks you can switch on Require a signature on every live call. With that setting, a stolen key alone is useless, because the thief does not have the secret. We recommend switching it on once your integration signs correctly.

Where keys must never be

  • In a mobile app or in JavaScript that runs in a browser. Anything delivered to a user's device can be read by the user.
  • In a public code repository.
  • In screenshots, tickets, chats or emails.
  • In the address of a request. Send the key in the header only.

Keep keys in the configuration of your server, outside the web folder, for example in environment variables. Your app or website should talk to your own server, and only your server talks to our API.

Revoke a key

  1. On the keys page, press Revoke beside the key.
  2. Confirm.

Applications using that key stop working immediately. A revoked key cannot be switched on again; create a new one.

Replace a key without downtime

  1. Create a new key.
  2. Put it on your server and deploy.
  3. Check on the keys page that the new key shows a recent "last used" time and the old one no longer changes.
  4. Revoke the old key.

Do this on a schedule, for example every six months, and at once when a person with access to the server leaves.

A key may have leaked

Act first, investigate afterwards:

  1. Revoke the key.
  2. Create a new one and deploy it.
  3. Look at Transactions for calls you did not make, and note their references.
  4. Check the IP whitelist under Security and webhooks for addresses you did not add.
  5. Open a ticket and tell us what happened.

"Invalid key" or "not allowed" answers

  • The key was revoked or has expired. The keys page shows its state.
  • A test key was sent to do a live transaction, or the other way round.
  • A live key was used from an address that is not on your whitelist.
  • The header name is wrong, or the key has a space or line break at the end from copying.
  • Signatures are required and the request was not signed, or the clock of your server is wrong by more than a few minutes.

Limits

Each account has a limit of calls per minute and transactions per day, shown at the bottom of the overview page. If you expect more, tell us before a campaign so the limits can be raised in time.

Was this article helpful?

Still stuck? Open a support ticket and our team will help.


Related articles

← Back

Chat with us
Hi! Send us a message and we will reply here as soon as we can.
Security check image
Chat with us