mTLS
Optional connection-level transport hardening
Mutual TLS (mTLS) is an optional connection-level hardening IDCanopy can enable per tenant. The standard, required authentication is the per-request bearer API key; mTLS is offered in addition for tenants whose security policy requires client-certificate authentication of the connection itself. It is not required by default, request it during onboarding if your policy calls for it. When enabled, mTLS authenticates the connection and the bearer key authenticates the tenant.
Issuance flow (CSR-based, you keep your private key)
- You generate a private key and a Certificate Signing Request (CSR). The private key never leaves your infrastructure and is never sent to IDCanopy.
- The CSR subject common name (CN) must be the value IDCanopy registers for your tenant. The
default form is
<tenant-slug>.clients.forensic.idcanopy.com; IDCanopy confirms the exact CN during onboarding. - Send the CSR (not the key) to IDCanopy. IDCanopy signs it with the forensic-api client CA and returns your client certificate.
- IDCanopy registers your CN against your tenant. On every request the proxy verifies the client certificate against the CA and passes the verified CN downstream; a request whose certificate CN does not match the registered tenant CN is rejected.
Parameters
| Item | Value |
|---|---|
| CA | IDCanopy forensic-api client CA, chain provided by IDCanopy ops |
| Client cert validity | 730 days (2 years) |
| Subject CN | <tenant-slug>.clients.forensic.idcanopy.com (confirmed per tenant) |
| Key | RSA, 2048 minimum, 4096 recommended, held by the tenant |
| Rotation | Re-issue before expiry via the same CSR flow; the old certificate stays valid until expiry, so rotate with overlap |
Staging vs production
Staging and production use separate CAs and separate registered CNs. A staging client certificate is not accepted in production and vice versa. Request both during onboarding if you integrate against staging first.
Request headers
The proxy verifies your certificate and forwards the verification result and certificate DN to the application internally. Integrators do not set these headers themselves, present a valid client certificate at the TLS layer and the proxy handles the rest.
To obtain a CA chain, request signing, or rotate a certificate, contact your IDCanopy onboarding contact.