mTLS Certificates & CSR

Every connection to the Axys API — staging or production — uses mutual TLS (mTLS): in addition to verifying Axys's server certificate (as your client would for any HTTPS connection), you present a client certificate that Axys verifies before your request is processed at all. This page covers how to generate that certificate, what its fields mean, and how to keep it current.

Step 1: Generate a key pair and CSR

Generate an RSA-2048 private key:

openssl genrsa -out client.key 2048

Create a CSR configuration file. The Subject fields establish your identity within the Axys platform hierarchy — see Program Architecture for how O and OU map to your Tenant and Program(s):

[req]
default_bits       = 2048
prompt             = no
distinguished_name = dn
req_extensions     = ext

[dn]
C  = US
ST = California
L  = San Francisco
O  = Acme Financial Services Ltd
OU = Acme Cards
CN = api.acmecards.example

[ext]
subjectAltName = @alt_names

[alt_names]
DNS.1 = api.acmecards.example
DNS.2 = staging.api.acmecards.example
IP.1  = 203.0.113.10

🚧

No wildcards. Every domain and IP address you intend to call the API from must be listed explicitly as a DNS or IP entry in subjectAltName. A wildcard such as *.acmecards.example will not be accepted. If you add a new calling domain or IP later, you'll need a new certificate covering it.

Generate the CSR:

openssl req -new -key client.key -out client.csr -config openssl.cnf

Verify its contents before submitting:

openssl req -in client.csr -text -noout

Step 2: Submit your CSR and receive your certificate

Submit the CSR to Axys through your onboarding contact. Axys's internal certificate authority validates the CSR's O/OU fields against your Tenant/Program records and signs it.

sequenceDiagram
    participant You
    participant CA as Axys Certificate Authority

    You->>You: Generate RSA-2048 key pair
    You->>You: Create CSR (O, OU, CN, SAN — no wildcards)
    You->>CA: Submit CSR
    CA->>CA: Validate fields against<br/>Tenant/Program records
    CA->>You: Signed client certificate (~24h)
    You->>You: Install certificate + private key

The certificate you receive is purpose-built for client authentication:

• Extended Key Usage: TLS Web Client Authentication only — it cannot be used as a server certificate
• Key Usage: Digital Signature, Key Agreement
• Validity: 90 days from issuance
• Issuer: Axys's internal certificate authority (a separate CA hierarchy exists for staging and production — certificates from one are not valid in the other)

📘

Axys can also provide the CA certificate chain if your environment requires it (for example, to build a PFX bundle that includes the full chain — see below).

Using your certificate

Production: raw key and certificate (PEM)

Most server environments — load balancers, reverse proxies, HTTP client libraries — accept the private key and certificate as separate PEM files, as used in the examples throughout this documentation:

curl --cert client.crt --key client.key -H "X-API-Key: ..." https://production.api.axyscards.com/v2/cardholders

Store client.key in a secrets manager appropriate to your infrastructure — see Security Compliance & Data Protection for broader key management guidance.

Development and testing: PFX bundle

Tools like Postman, and some browsers, expect a single PKCS#12 (.pfx/.p12) bundle rather than separate PEM files. Create one from your key and certificate:

openssl pkcs12 -export -out client.pfx -inkey client.key -in client.crt -certfile axys-ca-chain.pem

🚧

PFX bundles are convenient for local development but bundle your private key into a single password-protected file. Don't use PFX bundles in production services — use the raw PEM key loaded from a secrets manager instead.

Certificate lifecycle and renewal

stateDiagram-v2
    [*] --> Active
    Active --> Renewing: Submit new CSR (recommended at the 30-day reminder)
    Renewing --> Overlapping: New certificate issued (~24h)
    Overlapping --> Active: Old certificate retired from service
    Active --> Lapsed: Expiry reached without renewal
    Lapsed --> [*]

    note right of Active
        Expiry reminders sent at
        30 / 15 / 5 days before expiry
    end note

Certificates are valid for 90 days. Axys sends expiry reminders at 30, 15, and 5 days before expiry (see Webhooks & Callback Notifications for delivery details). To renew:

1. Generate a new key pair and CSR (you can reuse the same Subject fields).
2. Submit it the same way as your original CSR.
3. Once the new certificate is issued (~24h), deploy it alongside the old one — both remain valid during this overlap period, so there's no downtime window.
4. Once the new certificate is confirmed working in production, retire the old key pair.

For the operational rotation workflow and how this interacts with your API keys, see Credentials & Key Rotation, or for a step-by-step walkthrough, see Rotate mTLS Certificates.

What's next

• IP Allowlisting & Network Security — the certificate alone isn't sufficient; your calling IP and DNS configuration are checked too
• Authentication & Environments
• Credentials & Key Rotation