Skip to content
B2B GroupPartner API

Client certificates (mTLS)

A client can be locked to one or more client certificates. With the lock, a stolen client secret or token is useless without the private key of a registered certificate. It is optional, and it works alongside the IP allowlist.

How it works

  • The lock is opt-in per client. Register the SHA-256 fingerprint of each certificate your servers will present, in the developer portal or through the client update route. An empty list means no lock.
  • A registered fingerprint takes effect for new tokens. Request a new token after you change the list; a token issued before the change keeps the list it was issued with.
  • With fingerprints registered, your systems must present the certificate on the token request and on every call with the token. The TLS handshake asks for a client certificate; a connection without one still completes, and the request is then rejected.
  • The check fails closed. A request without a certificate answers 403 certificate_required; a request with a certificate that is not registered answers 403 certificate_not_allowed. On the token route this only happens when the credentials are correct, so the answer never reveals whether a client exists.
  • We check the fingerprint of the certificate, not its issuer. A self-signed certificate works as well as one from a public CA. Register the fingerprint of the new certificate before the old one expires; both stay valid until you remove the old fingerprint.
  • Both environments support it, each with its own client. Test in the sandbox first.

Generating the fingerprint

The fingerprint is the SHA-256 hash of the DER-encoded certificate, written as 64 hexadecimal characters without colons. Upper or lower case does not matter.

openssl x509 -in client.crt -noout -fingerprint -sha256
# sha256 Fingerprint=9F:86:D0:81:88:4C:...

Remove the colons before you register it, for example:

openssl x509 -in client.crt -noout -fingerprint -sha256 | cut -d= -f2 | tr -d ':'

If you do not have a certificate yet, a self-signed one is enough:

openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
  -keyout client.key -out client.crt -days 730 -subj "/CN=your-company-b2b-client"

Keep client.key private. Only the fingerprint is registered with us; we never see the key.

Testing

Register the fingerprint on a sandbox client, then:

  1. Request a token without the certificate - expect 403 certificate_required.
  2. Request a token with the certificate - expect 200.
  3. Call a route with that token but without the certificate - expect 403 certificate_required.
  4. Call it with another certificate - expect 403 certificate_not_allowed.

curl

curl -s https://api-sandbox.b2bgroup.dk/v1/oauth/token \
  --cert client.crt --key client.key \
  -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET"

curl -s https://api-sandbox.b2bgroup.dk/v1/codes/ABC-7K3Q-M8ZP/status \
  --cert client.crt --key client.key \
  -H "Authorization: Bearer $TOKEN"

C#

using System.Security.Cryptography.X509Certificates;

var handler = new HttpClientHandler();
handler.ClientCertificates.Add(X509CertificateLoader.LoadPkcs12FromFile("client.pfx", pfxPassword));
var http = new HttpClient(handler) { BaseAddress = new Uri("https://api-sandbox.b2bgroup.dk") };
// Request the token and set the Authorization header as in Authentication; every call now presents the certificate.

Node

import fs from 'node:fs';
import { Agent } from 'undici'; // the HTTP client behind fetch in Node 18+

const dispatcher = new Agent({
  connect: { cert: fs.readFileSync('client.crt'), key: fs.readFileSync('client.key') },
});
// Pass the dispatcher on every call, including the token request.
const response = await fetch(`${baseUrl}/v1/codes/ABC-7K3Q-M8ZP/status`, { headers, dispatcher });

Python

session = requests.Session()
session.cert = ("client.crt", "client.key")
# Every call through this session presents the certificate, including the token request.
token_response = session.post(f"{BASE_URL}/v1/oauth/token", data={
    "grant_type": "client_credentials",
    "client_id": os.environ["CLIENT_ID"],
    "client_secret": os.environ["CLIENT_SECRET"],
})

Errors

StatuserrorMeaning
403certificate_requiredThe client has registered certificates, but the request did not present one. Check that your HTTP client sends the certificate on every call, including the token request.
403certificate_not_allowedThe request presented a certificate whose fingerprint is not registered for the client. Compare the fingerprint of the certificate your client sends with the ones registered.

Both are returned on the token request and on every call with a token. A 403 can also be insufficient_scope or ip_not_allowed; always look at error.