Skip to main content
You will end up with two files:
  • es256-private.pem: keep this on the machine that calls our API. Never share it by email, chat, ticket or code repository.
  • es256-public.pem: send this to us for onboarding.

​
Before you start

You need OpenSSL 3.0 or later. Check with:
  • Windows: install it via winget, Chocolatey or Git for Windows.
  • macOS: the built-in version may be LibreSSL. Run brew install openssl if the output does not show OpenSSL 3 or later.
If your terminal reports that openssl is not recognised, install it and open a new terminal window.
Generate the keys on the machine that will call our API, whether a server or a laptop, so the private key never has to be copied elsewhere.

​
Step 1: Generate the keys

Run these commands in PowerShell, Command Prompt, bash or zsh. The first creates the private key (EC P-256, PKCS#8 format). The second derives the matching public key.

​
Step 2: Verify the keys

Run these commands before sending anything.
Check that:
  • The first command prints Key is valid.
  • The second shows ASN1 OID: prime256v1 and NIST CURVE: P-256.
  • es256-private.pem begins with -----BEGIN PRIVATE KEY-----.
  • es256-public.pem begins with -----BEGIN PUBLIC KEY-----.
If the private key begins with BEGIN EC PRIVATE KEY, convert it to PKCS#8:

​
Step 3: Protect the private key

Anyone holding es256-private.pem can request tokens as your organisation. Treat it like a production password.
Restrict access to the account that runs your integration:
  • In production, store it in a secrets manager such as Azure Key Vault, AWS Secrets Manager or HashiCorp Vault.
  • Never email it, attach it to a ticket, paste it into chat or commit it to a repository. If you test with Postman, keep it in the Postman Vault or as a current value only.
  • If you think it has leaked, tell us immediately.

​
Step 4: Send us the public key

Send only es256-public.pem to your Credit Benchmark contact. Include:
  • Your organisation name
  • The environment (Sandbox or Production)
  • A technical contact
  • The scopes you need
  • The key fingerprint
We use the fingerprint to confirm the key was not altered in transit. Calculate it with:
Use a separate key pair for each environment. Before you send, check that the attachment is es256-public.pem and that no private key file is attached. We may call your technical contact to read back the fingerprint before activating the key. Once the key is registered, we send your onboarding pack. See what you receive back.

​
Key rotation

Replace your key pair at least every 12 months, or immediately if the private key may have been exposed.
1

Generate a new pair

Repeat Steps 1 and 2 using new file names, such as es256-private-2027.pem.
2

Send the new public key

Send it as in Step 4, with the subject M2M API key rotation - [Your organisation name] - [Environment] and your existing OAuthClientId.
3

Receive a new KID

We reply with a new KID. Your OAuthClientId does not change.
4

Switch over

Switch your integration to the new private key and KID, then tell us. We revoke the old KID and you securely delete the old private key.
For a suspected leak, skip the overlap and ask us to revoke the old key straight away.