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: https://sandbox.bankingcircleconnect.com/
• Authorization URL:https://authorizationsandbox.bankingcircleconnect.com/

For Production:

• Base URL: https://www.bankingcircleconnect.com/ (note the www)
• Authorization URL:https://authorization.bankingcircleconnect.com/

⚠️

Check Your Proxy Settings

Ensure your proxy settings don't block calls to the URLs above. Whitelist these URLs to allow outbound traffic in both environments.

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. Tokens are set to expire after 5min. 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"
}

⚠️

Throttling behaviour

Tokens expire after 5 minutes. Should the amount of requests for tokens exceed what would be considered an acceptable level, a throttling mechanism will kick in and return a 429 (Too Many requests).

The throttling mechanism is based on the IP and the threshold is defined on minute basis.