Rotate mTLS Certificates

mTLS client certificates are valid for 90 days and must be renewed before they expire. This guide walks through the renewal process step by step — from generating a new key pair through to retiring the old certificate safely — with an emphasis on the overlap period that makes rotation zero-downtime.

When to rotate

Axys sends expiry reminders at 30, 15, and 5 days before a certificate's expiry timestamp, via the webhook URL registered in Account Management. Treat the 30-day reminder as your trigger to begin the renewal process — this gives comfortable time to generate a CSR, wait for the signed certificate (~24 hours), deploy and test, and retire the old certificate, all without urgency.

❗️
An expired certificate causes immediate, hard failure. If a certificate lapses, every API call using it fails at the TLS handshake — before the X-API-Key is checked and before any application- level error handling runs. There is no grace period. Don't treat the 5-day reminder as the action trigger.

Overview

sequenceDiagram
    participant Axys
    participant You

    Note over Axys,You: T-30 days
    Axys->>You: Expiry reminder callback (30 days)
    You->>You: Generate new RSA-2048 key pair
    You->>You: Create CSR with same O/OU/CN/SAN fields

    You->>Axys: Submit new CSR via Account Management
    Axys->>You: Signed certificate returned (~24h)

    You->>You: Deploy new cert + key to secrets store
    You->>Axys: Test call using new cert
    Axys->>You: 200 OK — new cert confirmed working

    You->>You: Update all services to use new cert
    You->>You: Retire old certificate from all services
    Note over You: Old cert still valid — overlap period
    Note over You: T-0 — old cert would have expired

Step 1: Generate a new key pair and CSR

Generate a fresh RSA-2048 private key:

openssl genrsa -out program-a-new.key 2048

Create the CSR using the same Subject fields as the certificate being renewed — O, OU, CN, and every SAN entry:

openssl req -new \
  -key program-a-new.key \
  -out program-a-new.csr \
  -config program-a-openssl.cnf

Verify the output before submitting:

openssl req -in program-a-new.csr -text -noout

Confirm that Subject and Subject Alternative Name fields match your existing certificate exactly. If your calling domains or IPs have changed since the original certificate was issued, update the CSR to reflect the current set — this is also an opportunity to add any new IP addresses or domains.

📘
Generate a new key pair, not just a new CSR. Reusing the same private key for a renewed certificate reduces the security benefit of rotation — a key that may have been exposed or is approaching the end of its useful life is carried forward rather than replaced. Best practice is to generate a fresh key pair on every renewal.

Step 2: Submit the CSR and retrieve the new certificate

Submit the PEM-formatted CSR via Account Management. The signed certificate is typically returned within 24 hours.

📘
Account Management is available only in the production environment. For any sandbox certificate rotation, contact your Axys account team directly — the same timing and process applies but the submission route differs.

Once received, verify the new certificate:

# Verify the certificate is signed by Axys's CA
openssl verify -CAfile axys-ca-chain.pem program-a-new.crt

# Confirm validity period
openssl x509 -in program-a-new.crt -noout -dates

# Confirm the key matches the certificate
openssl x509 -in program-a-new.crt -noout -modulus | md5sum
openssl rsa  -in program-a-new.key  -noout -modulus | md5sum
# Both MD5 hashes must match — if they don't, the key and cert are mismatched

Step 3: Deploy the new certificate alongside the old one

Load the new certificate and key into your secrets manager without removing the old ones:

Both the old and new certificates are valid simultaneously during the overlap period
Deploy the new certificate to your production environment alongside the existing one
Do not remove the old certificate yet

The precise deployment mechanism depends on your infrastructure (load balancer certificate binding, application-level certificate loading, secrets manager rotation, etc.) — ensure the new key and certificate are loaded as a matched pair.

Step 4: Test the new certificate

Make a test call using only the new certificate to confirm the full authentication chain works (certificate valid, IP allowlisted, FCrDNS passes):

curl --cert program-a-new.crt \
     --key program-a-new.key \
     -H "X-API-Key: YOUR_PROGRAM_API_KEY" \
     "https://production.api.axyscards.com/v2/cardholders"
# Expected: 200 {"status":"success","items":[...],"total":...}

If this returns a 403 rather than a 200, check:

Issue	Likely cause
New cert not accepted at TLS	Cert not yet trusted by the gateway — wait a few minutes after issuance and retry
`403 "No Authorised IPs configured"`	If you updated the `CN`/`SAN` fields in the new CSR (e.g., to add a new IP), the new domains/IPs may need to be allowlisted — see IP Allowlisting & Network Security

Step 5: Update all services and retire the old certificate

Once the new certificate is confirmed working:

Update all services, configurations, and deployment pipelines to reference the new certificate and key pair — not the old ones.
Confirm that no remaining service is still loading the old certificate.
Delete the old private key from your secrets manager and any other storage locations.
Update your certificate register with the new issue date and expiry.

🚧
Don't leave the old key in your secrets store "just in case." Once the new certificate is confirmed working, the old key is retired — keeping it accessible increases the attack surface without providing any benefit. If you need an emergency rollback path, use the overlap period to maintain both certs simultaneously, but set a hard deadline for retiring the old key.

If the certificate lapses

If a certificate expires before renewal completes, all calls using it will fail at the TLS handshake immediately and silently from the application layer's perspective — there will be no 401 or 403 HTTP response, just a TLS error.

Recovery path:

Raise a support ticket immediately, classifying it as priority: 1 (Critical)
Generate a new key pair and CSR
Submit via Account Management (or directly to your Axys account team if Account Management itself is inaccessible with the expired credential)

See Raising & Managing Support Tickets.

Rotate mTLS Certificates

When to rotate

Overview

Step 1: Generate a new key pair and CSR

Step 2: Submit the CSR and retrieve the new certificate

Step 3: Deploy the new certificate alongside the old one

Step 4: Test the new certificate

Step 5: Update all services and retire the old certificate

If the certificate lapses

Certificate rotation checklist

What's next