Authenticate and retrieve accounts

This guide walks you through the process of authenticating with the API and retrieving a list of accounts in the sandbox environment.

Before You Start

Ensure you have the following:

• A Machine to Machine (M2M) account set up in the sandbox environment with the correct access and permissions. This will be created for you during the onboarding process, including:
  • Username
  • Password
• A valid certificate for the M2M account. This will be provided to you during the onboarding process, and will consist of:
  • A PFX certificate file (.pfx)
  • The passcode for the PFX certificate

IP Whitelisting Requirements

• Inbound: Your IP address must be whitelisted for the M2M account
• Outbound: Your firewall must allow outbound traffic to the sandbox endpoints

Step-by-Step Guide

Step 1: Prepare Your Authentication

1. Locate your authentication credentials:

   • Username
   • Password
   • PFX certificate file
   • Certificate passcode

2. Encode your username and password in Base64 format:

// Example of encoding credentials to Base64
var raw = CryptoJS.enc.Utf8.parse('username' + ":" + 'password')
var base64 = CryptoJS.enc.Base64.stringify(raw)

Step 2: Get an Access Token

1. Prepare your request to the sandbox authentication endpoint:
   GET https://sandbox.bankingcircleconnect.com/api/v1/authorizations/authorize

2. Include these headers:

Content-Type: application/json
Authorization: Basic {your-base64-encoded-credentials}

3. Make the authentication request with your certificate:

# Example cURL request
curl -X GET https://sandbox.bankingcircleconnect.com/api/v1/authorizations/authorize \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic {your-base64-encoded-credentials}" \
  --cert-type P12 \
  --cert /path/to/your/certificate.pfx:your-certificate-passcode

Note: Replace the certificate path and passcode with your actual values

4. Save the response values:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Im9JMmRKVjdpTUkxZU9pZWFsb...",
    "expires_in": "300",
    "token_type": "Bearer"
}

• The token expires in 5 minutes (300 seconds)
• You'll need to request a new token after it expires

Step 3: Retrieve Your Accounts

1. Prepare your request:
   GET https://sandbox.bankingcircleconnect.com/api/v1/accounts

2. Include these headers:

Accept: application/json
Authorization: Bearer {your-access-token}

3. Make the request, using default pagination parameters:

curl --request GET \
  --url 'https://sandbox.bankingcircleconnect.com/api/v1/accounts?PageNumber=1&PageSize=50' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {your-access-token}'

4. Process the response:

{
  "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "accountDescription": "Description of the account",
  "accountIdentifiers": [
    {
      "account": "DK6289000049910085",
      "financialInstitution": "",
      "country": "DK"
    }
  ],
  "ibans": [
    "DK6289000049910085",
    "LU734080000049971008",
    "DE422022080000499910085"
  ],
  "status": "Active",
  "currency": "EUR",
  "openingDate": "2023-02-21T00:00:00+00:00",
  "closingDate": null,
  "ownedByCompanyId": "2920e27e-b112-4b09-8ae6-c6f4aaacd3c7",
  "ownedByCompanyName": "ACME industries Ltd",
  "ownedByCompanyNumber": null,
  "protectionType": "None",
  "balances": [
    {
      "type": "CurrentBalance",
      "currency": "EUR",
      "beginOfDayAmount": 999,
      "financialDate": "2024-02-21T00:00:00+00:00",
      "intraDayAmount": 0,
      "lastTransactionTimestamp": "2024-02-21T12:03:01.3099984+00:00"
    }
  ],
  "friendlyName": "",
  "netInterestRate": null,
  "interestCalcMethod": null,
  "overdraftRate": null,
  "overdraftRateCalcMethod": null
}

You have now successfully authenticated with the API and retrieved your account information. You can use this same authentication process for other API endpoints, remembering to refresh your token before it expires.

Troubleshooting Common Issues

Authentication Failures

• Certificate Missing or Invalid

  • Ensure you're passing both the certificate AND the Base64-encoded username/password
  • Just providing the username/password without the certificate will fail the SSL handshake
  • Verify your certificate passcode is correct
  • Check that you're using the correct certificate file

• IP Whitelisting

  • Ensure your outbound IP is whitelisted in our system
  • Check that your firewall allows outbound connections to our endpoints
  • If using a proxy or VPN, ensure those IPs are also whitelisted

Account Retrieval Issues

• 404 Not Found When Retrieving Accounts
  • Verify that your username has been granted access to accounts
  • Check with your administrator if you need additional permissions