Home / integration / mutual-tls-callouts
mutual-tls-callouts
Configure mTLS for Apex callouts using Named Credentials with client certificate authentication. NOT for standard TLS or API key auth — use architect/integration-security-architecture.
Open the skill folder on GitHub
Mutual TLS Callouts
Mutual TLS requires both sides to present certificates. Salesforce supports mTLS callouts via a client certificate stored in Setup → Certificate and Key Management, referenced from a Named Credential. This skill sets up the cert, the Named Credential, and a minimal Apex caller that proves the connection before shipping.
Adoption Signals
Partner APIs that mandate mTLS (banks, healthcare EDI, some government systems).
Recommended Workflow
- Generate a client keypair (or receive partner-signed cert) and import via Setup → Certificate and Key Management.
- Create Named Credential referencing the certificate; set endpoint + authentication protocol 'Per User' or 'Named Principal'.
- Write a small Apex probe:
HttpRequest req; req.setEndpoint('callout:MyPartner/health'); new Http().send(req);and assert 200. - Schedule a daily probe job with alerting; cert expiry surfaces 30+ days ahead.
- Rotate certificate annually or per partner policy.
Key Considerations
- Self-signed certs are fine for dev but production requires partner-signed.
Certificate expirationsurprises pages; monitorCertificate.ValidTo.- Named Credential is the only supported place to reference client cert — do not try to ship JKS in Apex.
- CSR generation happens in Salesforce; private key never leaves.
Worked Examples (see references/examples.md)
- Bank ACH partner — Daily batch callout
- Expiry monitor — Prevent cert outage
Common Gotchas (see references/gotchas.md)
- CSR generated externally — Private key material uploaded; weaker security.
- Missing intermediate chain — Handshake fails.
- No expiry alert — Outage Friday night.
Top LLM Anti-Patterns (full list in references/llm-anti-patterns.md)
- Generating CSR externally
- Missing intermediate chain
- No expiry monitor
Official Sources Used
- Apex REST & Callouts — https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts.htm
- Named Credentials — https://help.salesforce.com/s/articleView?id=sf.named_credentials_about.htm
- Connect REST API — https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/
- Private Connect — https://help.salesforce.com/s/articleView?id=sf.private_connect_overview.htm
- Bulk API 2.0 — https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/
- Pub/Sub API — https://developer.salesforce.com/docs/platform/pub-sub-api/guide/intro.html