Authentication and authorization

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.

Getting your M2M user set up

We will guide you through this process during onboarding. You will need to provide:

• An email address
• A list of IP addresses to whitelist

Our team will then guide you through the secure certificate setup process. This includes:

• Receiving your secure credentials
• Setting up your digital certificate
• Getting access to the sandbox environment

Note: You always need a certificate to test our endpoints, including for our sandbox environment.

Environment URLs

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:

Sandbox Environment

• Base URL: https://sandbox.bankingcircleconnect.com/
• Authorization URL: https://authorizationsandbox.bankingcircleconnect.com/

Production Environment

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

⚠️

Check Your Network Settings

Ensure both your proxy and firewall settings allow outbound traffic to the URLs above. You may need to:

• Whitelist these domains in your firewall configuration
• Configure your proxy settings to allow these URLs
• Ensure your network security policies permit outbound HTTPS traffic to these endpoints

Certificate-Based Authentication

Our APIs use GlobalSign certificates for secure authentication. Each certificate contains a unique ThumbPrint that identifies your API session requests.

Access Tokens

The API uses OAuth 2.0 JWT tokens for authorization (JWT OAuth 2.0 signed tokens). Here's how it works:

1. Send your certificate details, username, and password to the Authorization endpoint
2. Use Basic Authentication with Base64 encoding
3. Receive a JWT token containing your access rights
4. Include the token in subsequent API requests

Example of Base64 Encoding

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

Example Authorization Request

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

Token Management Best Practices

We encourage users to only request a new access token when required, i.e., only if the previous token has expired. Tokens expire after 5 minutes. Follow these steps:

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

Example Success Response

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

Rate Limiting

Should the amount of requests for tokens exceed what would be considered an acceptable level, a rate limiting mechanism will kick in. The rate limiting mechanism is based on the IP and the threshold is defined on a minute basis. When the rate limit is exceeded, the API returns a 429 - Too Many Requests response.

Security Measures

Transport Layer Security

All APIs enforce mutual TLS 1.2 encryption for secure data transmission.

Web Application Firewall (WAF)

Our security infrastructure includes:

• OWASP-compliant WAF protection against:
  • SQL injections
  • DDoS attacks
  • Cross-site scripting (XSS)
• 24/7/365 security monitoring through Managed Detection & Response service