Mutual TLS Setup

Apata supports mTLS in two directions:

📘

mTLS adds an additional layer of security by validating the identity of both parties, making it the recommended approach for securing sensitive API and webhook connections.

Outbound mTLS (Apata → Issuer)

Use this when Apata calls your endpoint - for example, Card Link requests, OOB webhooks, or the Finalised Event.

Step 1 - Apata generates a CSR

Apata creates a CSR containing its organisation details and a public key, and provides it to your team for signing.

Step 2 - Sign the CSR with your CA

Sign the CSR using your own CA or an internal CA. The signed certificate authorises Apata to connect to your system.

openssl x509 -req -in apata.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out apata-outbound.crt -days 365 -sha256

Step 3 - Provide the signed certificate to Apata

Return the following to Apata:

Step 4 - Configure your webhook

Add apata-outbound.crt and your CA certificate(s) to your webhook configuration. Apata will present this certificate on every outbound connection to your endpoint.

⚠️

Ensure the certificate validity period aligns with your security policies. Plan renewals at least 30 days before expiry to avoid service disruptions.

Inbound mTLS (Issuer → Apata)

Use this when your system calls the Apata API. You generate a CSR, Apata signs it, and you configure your API client to present the resulting certificate on every request.

Step 1 - Generate a private key and CSR

# Generate a 2048-bit RSA private key
openssl genrsa -out client.key 2048

# Create a CSR
openssl req -new -key client.key -out client.csr

You will be prompted for the following details during CSR creation:

⚠️

The Common Name (CN) must exactly match the domain or hostname used to connect to Apata.

Step 2 - Share the CSR with Apata

Send client.csr to the Apata support team via a secure channel such as encrypted email or the account portal.

Step 3 - Receive your signed certificate from Apata

Apata will return the following files:

Step 4 - Configure your API client

Update your client to present client.crt and client.key on every request. See the Code Examples below.

Code Examples

const fs = require('fs');
const https = require('https');

const httpsAgent = new https.Agent({
  cert: fs.readFileSync('client.crt'),
  key: fs.readFileSync('client.key'),
  ca: fs.readFileSync('apata_ca.crt') // optional - validates Apata's server certificate
});

const response = await fetch('https://api.apata.io', {
  method: 'POST',
  body: JSON.stringify({ message: 'Test' }),
  headers: { 'Content-Type': 'application/json' },
  agent: httpsAgent
});

CSR Requirements

Best Practices

Troubleshooting