mTLS Endpoints

For organisations whose security policies require mutual TLS (mTLS), Stitch provides dedicated endpoints that require a client certificate on every connection. The certificate authenticates your organisation at the transport layer, in addition to (not instead of) standard API authentication. Certificates can either be issued by the Stitch private Certificate Authority, or you can issue certificates from your preferred Certificate Authority and provide us with the certificate chain. This is discussed during the onboarding process.

Endpoints

mTLS Endpoint	Equivalent Standard Endpoint	IP Address
https://api.mtls.stitch.money	https://api.stitch.money	20.87.105.80
https://secure.mtls.stitch.money	https://secure.stitch.money	20.87.105.80

Both hostnames resolve to the same fixed IP address, which is reserved to Stitch and safe to allowlist in your egress firewall.

Getting Set Up

mTLS access is provisioned per organisation, coordinated through your Stitch onboarding team.

note

The process described below is applicable for certificates issued by Stitch's private Certificate Authority. Should you wish to issue your own certificates, discuss this with your onboarding team.

1. Generate a Private Key and CSR

Generate a keypair and a Certificate Signing Request (CSR) on your side.

note

Your private key never leaves your environment. Only the CSR is sent to Stitch.

openssl req -new -newkey rsa:4096 -nodes \
  -keyout stitch-mtls.key \
  -out stitch-mtls.csr \
  -subj "/C=ZA/O=Your Company/CN=stitch-prod.yourcompany.com" \
  -sha256

The certificate's Common Name (CN) is used to identify and authorize your traffic, so it must be unique and stable. Agree the CN with your Stitch onboarding team beforehand. The recommended convention is <purpose>-<environment>.<your-domain> (for example, stitch-prod.yourcompany.com).

Keep the private key (stitch-mtls.key) safe. Restrict access to it and store it in your secrets management system.

2. Send Us Your CSR

Send the CSR file (and optionally the egress IP ranges you will connect from) to your Stitch onboarding team via the agreed secure channel. The CSR contains only public information and is safe to transmit.

3. Receive Your Certificate Chain

Stitch signs your CSR with our private CA and returns the complete certificate chain either as a single PEM file (containing your leaf certificate, the issuing (intermediate) CA certificate, and the root CA certificate, in that order) or as three separate files. The chain imports directly into standard trust stores and TLS libraries.

Certificates are valid for one year (365 days) by default.

4. Test the Connection

Configure your TLS client with your private key and the issued certificate chain. Most TLS libraries present the chain automatically. For a quick verification with curl:

curl --cert stitch-mtls-chain.pem --key stitch-mtls.key \
  https://secure.mtls.stitch.money/connect/token \
  --location --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'audience=https://secure.stitch.money/connect/token' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET'

Common responses if something is misconfigured:

Response	Meaning
TLS alert unknown_ca / handshake failure	The presented certificate does not chain to the Stitch private CA or we have not trusted your CA chain (if you have issued the certificate yourself).
HTTP 403 RBAC: access denied	The handshake succeeded but your certificate's CN has not been enabled for this endpoint. Contact your Stitch onboarding team.
Connection timeout	Your egress firewall may be blocking the connection. Confirm 20.87.105.80 is allowlisted.

5. Certificate Lifecycle

• Proactive expiry monitoring: Stitch monitors certificate validity at the mTLS gateway and tracks the certificates we issue, alerting internally as expiry approaches. We will reach out ahead of time to coordinate a rotation, so an expiring certificate should never take you by surprise. This applies whether the certificate was issued by Stitch or by your own CA. We'll send a reminder at 60 days, 30 days, 14 days, and 7 days prior to expiry.
• Renewal: Ahead of the one-year expiry, generate a new CSR (a new key is recommended) and repeat the issuance flow with your Stitch onboarding team.
• Compromise or revocation: If your private key is ever compromised, contact Stitch immediately! Your certificate's access is revoked at the gateway without affecting other credentials.

note

mTLS secures the connection. Your API calls are still authenticated as normal. Continue to use your client credentials exactly as you would on the standard endpoints, including the unchanged audience value of https://secure.stitch.money/connect/token.