Authentication & Environments

Every request to the platform's API is authenticated twice: once at the transport layer, via mutual TLS, and once at the application layer, via an API key. Both factors are required on every request, in every environment. Neither factor is optional, and neither is sufficient on its own.

❗️

A request presenting a valid X-API-Key but no client certificate, or a valid certificate but no X-API-Key, will be rejected. If you're integrating against the platform for the first time, set up both before attempting any call, including sandbox calls.

Factor 1: the mTLS client certificate

During onboarding, you (or your Tenant administrator) generated a certificate signing request and received a signed client certificate back from the platform. This certificate must be presented on the TLS connection for every API request — it's checked before your X-API-Key is ever inspected.

The certificate also implicitly carries your identity: its O field identifies the Tenant and its OU field(s) identify the Program(s) it's valid for — see Program Architecture for how this maps to the credential hierarchy.

A successful TLS handshake with a valid certificate is necessary but not sufficient: your calling IP address must also be allowlisted, and must pass a forward-confirmed reverse DNS (FCrDNS) check against the domains in your certificate. The combination of these checks is covered in full in IP Allowlisting & Network Security; if you haven't completed that setup yet, start with Platform Onboarding: Overview & Checklist.

For how to generate a certificate signing request, receive your certificate, and rotate it before expiry, see Mutual TLS, Certificates & CSRs.

Factor 2: the API key (X-API-Key)

Every request must also include an X-API-Key header. As covered in Program Architecture, there are two distinct scopes of API key:

A program-level API key implicitly scopes every request to that one Program — there's no programId parameter anywhere in the API, because the key itself determines it. If you're holding tenant-level credentials, none of the endpoints in the Reference section will work for you; you're at the wrong layer.

Environments

The platform provides separate sandbox and production environments. Each has its own base URL, its own program-level API keys, and its own mTLS client certificate — credentials from one environment will not work in the other.

🚧

The staging and sandbox certificate is the same, but it is separate to the production certificate, even if you've already completed onboarding for one environment. If your production calls are failing with certificate or IP-allowlist errors, confirm you're using the production certificate and an allowlisted production IP — not your sandbox setup. See IP Allowlisting & Network Security.

Anatomy of an authenticated request

flowchart LR
    A["Your server"] -->|"1. TLS handshake with<br/>client certificate"| B["Axys API Gateway"]
    B -->|"2. Verify certificate +<br/>IP allowlist + FCrDNS"| B
    A -->|"3. X-API-Key header"| B
    B -->|"4. Verify API key,<br/>resolve Program scope"| B
    B -->|"5. Process request"| C["Cardholders / Cards /<br/>Wallets / etc."]

Making your first authenticated request

Every request needs your client certificate and private key (for the TLS handshake) and your program-level API key (as a header):

curl --cert /path/to/your-client-cert.pem \
     --key /path/to/your-private-key.pem \
     -H "X-API-Key: YOUR_PROGRAM_API_KEY" \
     -H "Content-Type: application/json" \
     "https://staging.api.axyscards.com/v2/cardholders"

If both factors are valid, your calling IP is allowlisted, and the FCrDNS check passes, you'll receive a 200 response. See Your First API Call for a full walkthrough including creating your first cardholder.

Storing your credentials

Both your client certificate's private key and your X-API-Key value are sensitive credentials:

• Never commit them to source control or include them in client-side (browser/mobile) code.
• Store them in a secrets manager appropriate to your infrastructure, and load them at runtime.
• Treat a leaked API key the same as a leaked password — rotate it immediately. Treat a leaked private key as a certificate compromise. See Mutual TLS, Certificates & CSRs for re-issuance.

For the platform's broader approach to key management and custody (including how private keys for digital-asset operations are protected), see Security, Compliance & Data Protection.

If authentication fails

What's next

• Your First API Call
• Errors & Status Codes
• Mutual TLS, Certificates & CSRs