mTLS Client Certificates

When the operator marks your client as requiring a certificate (require_certificate = true), every call, including the token request, must be made over a TLS connection on which your client presented the certificate issued to it. Possession of the private key is proven by the TLS handshake itself; nothing goes in an HTTP header.

Who issues the certificate?

You never generate the certificate yourself. The platform operator issues it for your client from the panel, signed by the environment's client CA. The platform keeps only the public certificate and its SHA-256 fingerprint. The private key is shown once, at issue time, and cannot be retrieved later: store it in your secret manager immediately.

What you receive

File	Contents	Keep it where
client.crt	Your leaf certificate (PEM CERTIFICATE). Its subject CommonName is your client_id.	With your client configuration.
client.key	The matching private key (PEM PRIVATE KEY).	Your secret manager only. Never send it to anyone.

A certificate is valid for one year. Each environment (test, production) has its own client CA, so a certificate issued for test does not open production.

Presenting the certificate

Configure your HTTP client to present the certificate and key during the TLS handshake (curl --cert --key semantics):

curl --cert client.crt --key client.key \
  --request POST \
  --url 'https://integration-api.tokenizationtr.com/v2/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{"client_id": "<client_id>", "client_secret": "<client_secret>", "grant_type": "client_credentials"}'

curl --cert client.crt --key client.key \
  --url 'https://integration-api.tokenizationtr.com/v2/admin/tokens/68aeb272d9336c619ce249f6' \
  --header 'Authorization: Bearer <access_token>'

How it is checked:

1. The platform's edge terminates TLS and verifies that the certificate you present chains to the environment's client CA. The handshake accepts connections without a certificate too, so clients that do not require one keep working.
2. For a client that requires a certificate, the integration service then demands that the edge verified a certificate on this connection, and that this certificate is exactly the one issued to your client (SHA-256 fingerprint match), is within its validity period and names your client_id as its CommonName.

There is no header alternative. An X-Client-Cert header, which earlier versions of this page described, is ignored.

Failure responses

Situation	Token endpoint	Other endpoints
No certificate presented on the connection	401, code 10005	401
Certificate not signed by the environment's client CA	401, code 10005	401
A valid certificate, but not the one issued to your client (for example an older one replaced by a regenerate)	401, code 10005	401
Certificate expired or not yet valid	401, code 10005	401
CommonName is not your client_id	401, code 10005	401
Your client requires a certificate but none was ever issued to it	401, code 10005	401
Your client does not require a certificate	Check skipped	Check skipped

A 401 while your bearer token is fresh almost always means a certificate problem. A client flagged as requiring a certificate with no certificate on record cannot be admitted at all: ask the operator to regenerate it.

Rotation

Ask the operator to regenerate the certificate before it expires. Regenerating issues a new key pair and replaces the stored fingerprint, so the previous certificate stops working immediately: deploy the new pair at the moment it is issued.

Checklist

• Store client.key from the issue screen in your secret manager. It is not recoverable later.
• Present client.crt + client.key in the TLS handshake on every call, including POST /v2/oauth/token.
• Use the certificate issued for the environment you are calling.
• Track the certificate's expiry and ask for a regenerate in time.