API Self Service

This guide walks you through setting up PKI-based API authentication in the BCB Client Portal. You will:

  1. Create a service account that represents your integration.
  2. Issue one or more API signing keys for that service account from your own certificate signing request (CSR).
  3. Manage the lifecycle of those keys: rename, revoke, filter and report.

All configuration lives under Developers → API management in the left-hand navigation.

📘

Key concepts

  • Service account: a non-human identity linked to exactly one counterparty. It defines where requests may come from (IP allowlist), what they may do (entity permissions), and who is notified of changes.
  • Signing key: a credential issued to a service account from your CSR. Each key has a Key ID (KID), an algorithm, and an expiry date. Your integration signs API requests with the private key that matches the CSR.

Before you begin

Make sure you have:

  • Access to the BCB Client Portal with permission to manage API access for your counterparty.
  • A mobile phone registered to your user. Creating a service account is confirmed with an SMS code.
  • The public IPv4 addresses or CIDR ranges your integration will call the API from.
  • A PEM-encoded PKCS#10 CSR generated from a private key that you control (see Generate a CSR).

The API management page

Go to Developers → API management. The page has two tabs:

TabWhat it shows
Service AccountsYour service accounts, grouped by counterparty, with a count of active and revoked keys for each.
API Signing KeysEvery signing key across all service accounts, with a status summary, filters and a report download.

Use the search box to find a service account by counterparty or service account name. Click the arrow next to a counterparty to expand its service accounts.




Create a service account

  1. On the Service Accounts tab, click Create service account (top right).
  2. Complete the form:
FieldRequiredNotes
Service account nameYesA recognisable name, e.g. Payments integration – production.
DescriptionNoFree text to help your team identify the account.
IP allowlistYesEnter an IPv4 address (e.g. 203.0.113.10) or CIDR range (e.g. 198.51.100.0/24) and press Enter to add it. Add as many as you need. Requests must come from at least one listed address.
Notification emailsYesEnter an address and press Enter to add it. These addresses are notified about service-account and signing-key changes. All Admin and API managers for the counterparty are notified automatically as well.
CounterpartyYesSelect the counterparty the service account acts for. A service account can be linked to only one counterparty.

🚧

Press Enter to add each value

IP addresses and email addresses are only saved once they appear as a tag below the field. If you type an address and don't press Enter, you will see "At least one notification email is required" or a similar validation message.

  1. After you select a counterparty, the Entity Permissions section shows the permissions you can grant. Switch on the ones your integration needs:
PermissionWhat it allows
ViewRead-only access. Always on.
Payment InitiatorCreate payments.
Payment ManagerApprove and decline payments.
Beneficiary ManagerAdd, edit and delete beneficiaries.
Virtual Account ManagerManage virtual accounts.

📘

Least privilege

Grant only the permissions the integration actually uses. For example, a reporting integration only needs View.

  1. Click Create service account.
  2. Enter the verification code sent by SMS to your registered phone number, then click Verify. If the code doesn't arrive, wait for the timer and click Resend a new code.

  1. When you see Service account created, click Done.


The new service account now appears under its counterparty on the Service Accounts tab.


View a service account

Click a service account name to open its details page. It shows:

  • Name, description and creation date.
  • Counterparty, Permissions, IP allowlist and Notification emails.
  • A Signing keys table for this service account, with a status filter.

Click Service Accounts (breadcrumb, top left) to go back to the list.


Edit a service account

  1. Open the service account and click the ⋮ menu (top right of the details card), then Edit. You can also use the ⋮ menu on the service account's row in the list.
  2. Update the name, description, IP allowlist, notification emails or entity permissions.
  3. Click Update service account.

🚧

Changes apply to all active keys

Changes to a service account affect all of its active signing keys immediately. For example, removing an IP address from the allowlist will cause requests from that address to fail, whichever key signed them.

The counterparty can't be changed after creation. To move an integration to a different counterparty, create a new service account.


Create a signing key

Generate a CSR

You generate the key pair yourself. BCB receives only the CSR, never your private key. For example, with OpenSSL:

# Generate a 2048-bit RSA private key and a PKCS#10 CSR (PEM encoded)
openssl req -new -newkey rsa:2048 -nodes \
  -keyout bcb-signing.key \
  -out bcb-signing.csr \
  -subj "/CN=my-service-account"

Keep bcb-signing.key secret and store it securely, for example in a secrets manager or HSM. Upload bcb-signing.csr in the portal.

📘

The example is for illustration only. Follow your organisation's key-management policy for key size, storage and rotation. The algorithm you select in the portal (e.g. PS256, RSASSA-PSS with SHA-256) must match how your integration signs requests.

Issue the key in the portal

  1. Open the service account and click Create signing key (top right).
  2. Complete the form:
FieldRequiredNotes
Key nameYesE.g. prod-key-2026.
DescriptionNoFree text.
Expire dateYesPick a date with the calendar. The number of days from today is shown under the field.
AlgorithmYesThe signing algorithm, e.g. PS256.
CSR uploadYesClick Choose file and select your PEM-encoded PKCS#10 CSR.

  1. Click Create signing key.

  2. The Key ID (KID) is shown once the key is created. Click the copy icon and store it securely, then click Done.


❗️

Copy the KID now

You won't be able to see the full KID again. After this screen, the portal only shows the last 7 characters.

The key now appears in the service account's Signing keys table with the status Active, its short Key ID, the Valid until date and Last used time.


👍

Rotating keys without downtime

A service account can have several active keys at once. To rotate, create a new key, move your integration to it, confirm requests succeed (check Last used), then revoke the old key.


Rename a signing key

  1. In the Signing keys table, click the ⋮ menu on the key's row and choose Edit.
  2. Change the Key name and/or Description.
  3. Click Update signing key.

📘

Renaming a key does not rotate it. Integrations keep using the same key material until you revoke it.


Revoke a signing key

Revoke a key when it's no longer needed, when you have rotated to a new key, or if you think the private key has been compromised.

  1. In the Signing keys table, click the ⋮ menu on the key's row and choose Revoke.
  2. Check the key details shown (Key ID, service account, valid until, last used).
  3. To confirm, type the last 7 characters of the Key ID. A Matches indicator appears when they're correct.
  4. Click Revoke key.

❗️

Revocation is immediate and permanent

Requests signed with a revoked key start failing straight away. This can't be undone. You'll need to create a new key to restore access.


Delete a service account

You can only delete a service account once it has no active signing keys. If any key is still active, Delete is greyed out in the menu and a message tells you to revoke all active keys first.


To delete a service account:

  1. Revoke all of its active signing keys (see Revoke a signing key).

  2. On the Service Accounts tab, click the ⋮ menu on the service account's row and choose Delete.

  3. Check the confirmation, then click Delete.


❗️

Deleting a service account is permanent and can't be undone.


Monitor keys on the API Signing Keys tab

The API Signing Keys tab shows every signing key for your organisation in one place.


Summary: counts of All keys, Active, Expiring soon, Expired and Revoked.

Table columns: Key name, Key ID (last 7 characters), Service account (and its counterparty), Expire at, Last used, Status, and a ⋮ actions menu.

Key statuses

StatusMeaning
ActiveValid and can be used to sign requests.
Expiring soonStill valid but approaching its expiry date. Plan a rotation.
ExpiredPast its expiry date and no longer accepted.
RevokedManually revoked and no longer accepted.

Search and filter

  • Use the search box to search by key name, counterparty or service account.

  • Click Status, tick one or more statuses, then click Apply filter. Click Clear filter to reset.

  • Click a column header to sort.



Download a signing-key report

  1. On the API Signing Keys tab, click Download report (top right).

  2. Select the Counterparty. Each report covers one counterparty.

  3. Choose the File format (e.g. .PDF).

  4. Under Status, tick All statuses or the specific statuses you want.

  5. Click Download.


The report shows the generation date, a status summary, a table of keys (Key, Key ID, Service account, Valid until, Last used, Status) and the configuration of each service account included (permissions, IP allowlist and notification emails). It's useful for periodic access reviews and audits.



Troubleshooting

SymptomLikely cause / fix
"At least one notification email is required"Type the email and press Enter so it appears as a tag.
Delete is greyed out for a service accountThe account still has an active signing key. Revoke all active keys first.
Requests fail after editing a service accountCheck that the calling IP is still on the IP allowlist and that the needed entity permissions are still switched on.
Requests fail with a key that used to workCheck the key's status on the API Signing Keys tab. It may be Expired or Revoked.
Lost the full Key IDThe full KID is only shown once, when the key is created. Create a new key, move your integration to it, and revoke the old one.
SMS code not receivedWait for the timer to finish and click Resend a new code. Check that your registered phone number is correct.

Need help? Use Support in the bottom-left of the portal to contact the BCB team.