Connect to the API

To use our APIs, you will need a Machine to Machine (M2M) user with the correct account access and permissions. The first step is to get issued a certificate that can be used when requesting access tokens.

You can then request access tokens (standard JWT 0Auth 2.0 signed tokens) by calling our Authorization endpoint and using your certificate, username, and password.

Getting your M2M user set up

Your integration manager will guide you through this process. You will need to provide us with an email address and a list of IP addresses to whitelist, after which you will be issued a certificate.

When receiving the initial passphrase for the certificate, please use this to reset the password. After changing the password, download the certificate that contains the Thumbprint which is used to request access tokens.

Note that you always need a certificate to test our endpoints, including for our sandbox environment. See API security for additional details.

Use the correct base URL

The Sandbox and Production environments are separate, and each requires its own set of credentials. Although the authentication method is the same across both environments, ensure you use the correct base URLs:

For the Sandbox:

  • Base URL:
  • Authorization URL:

For Production:

  • Base URL: (note the www)
  • Authorization URL:

Calling our APIs

To call our APIs, add the access token to the Authorization field in the request header. You need to use the Bearer Authentication scheme.

Example of encoding the username and password to Base64:

var raw = CryptoJS.enc.Utf8.parse('username' + ":" + 'password')
var base64 = CryptoJS.enc.Base64.stringify(raw)

Example of an authorization request:

  "url": "authorizationURL",
  "method": "GET",
  "header": {
    "Content-Type": "application/json",
    "Authorization": "'Basic ' + base64"

We encourage users connecting to the API to only request a new access token when required, i.e., only if the previous token has expired. This means that you should check the expiration time of the previous token before requesting a new one:

  1. Initiate a GET request to the Authorization endpoint
  2. Store the access_token (JsonWebToken) and expires_in values (in seconds) from the response body
  3. Check the expiration time of the token before every subsequent request:
    1. If the token hasn’t expired, then use the currently stored token in the new request
    2. If the token has expired, then follow the steps again to request a new token

Here's an example 200 success response containing the access token and expiry:

  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Im9JMmRKVjdpTUkxZU9pZWFsb nhCZ3lNb1pmOExRMmc2UGExUlVvdElVSFUifQ.eyJpc3MiOiJodHRwczovL2JhbmtpbmdjaXJjbGVub25wcm9kdGVuYW50LmIyY2xvZ2luLmNvbS9jNTUwZmZkZi01YWIyLTRjZTctYmM1NS0zNmU1YmIzZmYzYWQvdjIuMC8iLCJleHAiOjE1ODQwOTExMTIsIm5iZiI6MTU4NDA5MDgxMiwiYXVkIjoiYzZmMDEyNDgtYmNmYS00MDZhLWE3OTEtODRiNzE0MjM0NmM2Iiwic3ViIjoiYWE2ZTM3ODItNzExYi00MDY2LTliYzYtNDQ5ZDZlYzE5M2FiIiwib2lkIjoiYWE2ZTM3ODItNzExYi00MDY2LTliYzYtNDQ5ZDZlYzE5M2FiIiwibmFtZSI6IkFQSSBUZXN0dXNlciIsInVzZXJUeXBlIjoiNCIsInRodW1icHJpbnQiOiI2MDgzNzhCRkE2RTVFMkMwMUY3MDlBMzVENkREQjNBNkY4NDQ1NkUxIiwiYXpwIjoiYzZmMDEyNDgtYmNmYS00MDZhLWE3OTEtODRiNzE0MjM0NmM2IiwidmVyIjoiMS4wIiwiaWF0IjoxNTg0MDkwODEyfQ.nrjkLoivWiXHI0QuHSa_W7JmT V_KUs7zQWrf7-ko6oM1LMwLiHpM0w45d8PhxjNdG_o3hTmx8PhBkhvKoStlnkNzNGD4RYw3ZvpUjL5tuQpRPoY2xJ682R8u7pSN5kZvH0PCh2d0OVCD_twRVNFxdC5pYkabAlCgDE15RO0ZVxxBu6VFIe6 v9GaWxLL5Gn0NZgSZ1WzeP8RYgzrH3W7dRIXRHMe6fJBqCf9E7YXGUYuVRQ4l_PytnkICXiIX0e00xqwDwwEkpy_-1aAfkpk56QCEOfzO-QJwln2qbEU3S6okzsCvKvNbprqvmKbyjgknPuoGQjIVpM_sLloa2oA",
  "expires_in": "300"

What’s Next

Find out how you can use the Sandbox to safely test our APIs and set up your integration.