Mutual TLS for API Requests

Mutual TLS (mTLS) adds certificate-based client authentication to the requests your servers make to Atomic's API. With standard TLS, your client verifies Atomic's server certificate. With mTLS, Atomic also verifies a client certificate that your server presents during the TLS handshake, so a connection is only accepted when it carries a certificate Atomic has been configured to trust.

mTLS is optional. It is an additional layer on top of your API key and secret, not a replacement. Requests to the mTLS endpoint still need the same authentication headers as requests to the standard endpoint.

How it works

Atomic terminates mTLS at a dedicated load balancer in front of the same API that serves the standard endpoints. The load balancer validates that your client certificate chains to a certificate authority (CA) in a trust store configured for your account, then forwards the request to the API. Your API key and secret are checked as usual after that.

Because mTLS is enforced at the edge, it uses a different hostname per environment:

Paths, request bodies, and responses are identical between the two hosts. Only the hostname and the client certificate differ. The server certificate on the mTLS hosts is issued by a public CA (Amazon Trust Services), so no additional CA needs to be installed on your side to trust Atomic.

Certificate requirements

The requirements below are what Atomic enforces plus Atomic's recommendations.

Issuing a client certificate

There are two ways to obtain a client certificate Atomic will trust. Either way, your private key is generated on your side and never leaves your systems.

Option A: Atomic signs your CSR

This is the simplest option and the one Atomic recommends. You generate a key pair and a certificate signing request (CSR) per environment and send Atomic the CSRs. Atomic signs them with its private CA and returns the signed certificates along with the CA chain. Nothing needs to be added to Atomic's trust store because the certificates already chain to a CA Atomic trusts.

1. Generate a private key and CSR for each environment.
2. Send the CSRs (PEM, public material only) to your Atomic representative. Never send the private key.
3. Atomic returns the signed leaf certificate plus the issuing and root CA certificates.
4. Configure your HTTP client with the leaf certificate and your private key.

# ECDSA P-384 private key (keep this on your side)
openssl ecparam -name secp384r1 -genkey -noout \
  -out atomic-client-sandbox.key

# CSR to send to Atomic for signing
openssl req -new -key atomic-client-sandbox.key \
  -subj "/CN=atomic-client-sandbox.example.com/O=Example Bank" \
  -out atomic-client-sandbox.csr

# Repeat with a distinct CN for production, e.g.
# /CN=atomic-client-prod.example.com

Option B: Your CA issues the certificate

If your organization runs its own PKI, it can issue the client certificate directly. Send Atomic the public CA chain (root and any intermediates) for each environment, and Atomic adds that chain to the trust store for your account. Any leaf certificate your CA issues under that chain, with the clientAuth key usage, is then accepted.

Tell Atomic the CN values you plan to use so they can be documented alongside your account. Send only public material: the CA certificates and, optionally, the leaf certificate. Never send a private key.

Making requests

Configure your HTTP client or egress gateway to present the client certificate and private key on connections to the mTLS host, and include your API key and secret as you would on the standard host. Use a separate certificate for sandbox and production and keep the two configurations isolated.

curl https://api2.atmcsbx.com/access-token \
  --cert atomic-client-sandbox.pem \
  --key atomic-client-sandbox.key \
  -H "x-api-key: $ATOMIC_API_KEY" \
  -H "x-api-secret: $ATOMIC_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "identifier": "YOUR_USER_IDENTIFIER" }'

To confirm the setup, make a request with the certificate and expect a normal API response. Then make the same request without a certificate and confirm the TLS handshake is rejected. A handshake failure means the certificate was not presented, has expired, or does not chain to a trusted CA. An HTTP 401 after a successful handshake means the API key or secret is wrong.

Renewal and rotation

Track the expiry of your client certificates and begin renewal at least 30 days before they expire. What renewal involves depends on how the certificate was issued:

• Atomic-signed certificates: generate a new CSR (reusing or replacing your key, your choice) and send it to Atomic. Atomic returns a new signed certificate. Swap it in on your side; no other coordination is needed because the CA chain is unchanged.
• Certificates from your own CA: renew the leaf certificate as usual. Nothing changes on Atomic's side as long as it still chains to the CA Atomic trusts. If your root or intermediate CA changes, send Atomic the new chain at least 30 days before cutover so both chains can be trusted during the transition.

If you suspect a private key has been compromised, revoke the certificate at your CA where applicable and contact Atomic immediately so trust for it can be removed.

Limitations

• PayLink endpoints that route through Atomic's PCI Card Data Environment do not currently support mTLS. Direct deposit and other non-PCI endpoints do.
• mTLS does not restrict which source IP addresses can call the API. It authenticates the certificate, not the network.
• mTLS does not remove the need for API credentials. Both layers are always in effect on the mTLS hosts.

Further reading