What is mTLS?

Mutual TLS (mTLS) is a security protocol that enhances the standard TLS protocol by requiring both the client and the server to authenticate each other using digital certificates. This ensures that only trusted parties can establish secure communication.

Key Features of mTLS

1. Two-Way Authentication: Both the client and server present certificates to verify their identities.
2. Secure Data Transmission: All communication is encrypted, protecting sensitive data from unauthorized access or tampering.
3. Trusted Certificates: Certificates are issued by trusted Certificate Authorities (CAs) and used to establish trust between parties.

Why Use mTLS?

mTLS provides a higher level of security by combining encryption with mutual authentication, making it ideal for securing APIs, webhooks, and sensitive data exchanges.

How mTLS Works

1. Certificate Exchange: Both the client and server exchange certificates to verify their identities.
2. TLS Handshake: A secure handshake is performed, generating session keys for encrypted communication.
3. Encrypted Communication: All data exchanged is encrypted, ensuring privacy and integrity.

mTLS for Public APIs

To ensure secure access to Truv's public APIs, mTLS is implemented for the following endpoints:

• Production: api-mtls.truv.com
• Sandbox: api-sandbox-mtls.truv.com

Steps to Connect

1. Generate a Private Key and CSR

   • Use supported formats (e.g., X.509v3, RSA/ECDSA keys, SHA256).
   • Include details like the common name, organization, and location.
     Text

     CN: api-mtls.<name>.truv.com
     O: Truv Inc
     L: Miami
     ST: Florida
     C: US
     

2. Submit CSR to Truv

   • Truv will issue a signed certificate valid for one year.

3. Connect to API

   • Use the signed certificate and private key to authenticate the connection.
   • Example with curl
     Text

     curl --cert $CERT.pem --key $PRIVATE_KEY.key $URL
     

4. Work with Truv Support

   • Finish set-up and enable for your account.

5. Update Firewall Configuration

   • Allow the following IP addresses for Truv’s mTLS endpoints
     • Production
       • 35.167.32.174
       • 35.165.53.192
       • 54.71.147.242
     • Sandbox
       • 44.235.37.104
       • 35.83.220.165
       • 52.38.209.190

6. Use Truv's Client ID and Access Key

   • Please see our documentation about API Keys.

mTLS for Webhooks

Truv supports mTLS for webhook communication, ensuring secure and trusted data exchange between Truv and its clients.

Webhook Authentication Options

1. Using Truv’s Signed Certificate

   • Truv provides a public certificate (domain: mtls-prod.truv.com) that clients can configure on their server to establish an mTLS connection.

2. Using Client-Signed Certificate:

   • Truv can submit a Certificate Signing Request (CSR) to the client.
   • The client issues a signed certificate, which Truv uses along with the private key for authentication.

Originating IP Address

Please see our public documentation here about what IP addresses are in use for webhooks. Some clients will require explicit configuration to enable access by Truv.

Configuring Custom Headers for Webhooks

Truv allows clients to configure custom headers when invoking webhooks. This can include passing a Client ID and Client Secret for additional authentication. Please work with Truv to configure these settings.