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 403certificate_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:
- Request a token without the certificate - expect 403
certificate_required. - Request a token with the certificate - expect 200.
- Call a route with that token but without the certificate - expect 403
certificate_required. - 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
| Status | error | Meaning |
|---|---|---|
| 403 | certificate_required | The 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. |
| 403 | certificate_not_allowed | The 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.