Enforcing mTLS on Your Veryfi API Requests
Mutual TLS (mTLS) is an optional security upgrade for your Veryfi API integration. When enabled, both sides of every API connection verify each other's identity using certificates, not just the server proving itself to the client. This eliminates entire classes of attack, including credential theft, request forgery, and man-in-the-middle interception.
mTLS is available for customers with Platinum SLA Level
What is mTLS and why does it matter?
Standard HTTPS has the server present a certificate so the client knows it is talking to the real Veryfi. mTLS adds the reverse: your client also presents a certificate, and Veryfi verifies it before the connection is allowed to proceed.
This means that even if an attacker obtained your API key and CLIENT_SECRET, they still could not make a single API call without also holding your private certificate key. It is a strong second layer on top of standard API key authentication.
How to set up mTLS for your account
mTLS is configured at the account level. Once enforced, every request to the Veryfi API from your integration must present a valid client certificate or the connection will be rejected.
Step 1: Contact Veryfi to enable mTLS
mTLS is not self-serve today. Reach out to [email protected] or your account manager to request mTLS enforcement for your account. Include your CLIENT_ID so the team can locate your profile.
Step 2: Generate a client certificate and private key
If you do not already have a certificate, generate one using OpenSSL:
bash
# Generate a private key openssl genrsa -out client.key 2048 # Generate a certificate signing request (CSR) openssl req -new -key client.key -out client.csr # Self-sign the certificate (or submit the CSR to your internal CA) openssl x509 -req -days 365 -in client.csr -signedkey client.key -out client.crt
If your organization uses an internal certificate authority, submit the CSR there instead and use the signed certificate they return.
Step 3: Share your certificate with Veryfi
Send your client.crt (public certificate only, never the private key) to Veryfi. The team will register it against your account. Your private key never leaves your infrastructure.
Step 4: Update your API calls to present the certificate
Add your certificate and private key to every request. Here are examples for common tools:
curl:
bash
curl -X POST https://api.veryfi.com/api/v8/partner/documents/ \ --cert client.crt \ --key client.key \ -H "CLIENT-ID: YOUR_CLIENT_ID" \ -H "AUTHORIZATION: apikey USERNAME:API_KEY" \ -H "Content-Type: application/json" \ -d '{"file_url": "https://cdn.example.com/invoice.jpg"}'Python (requests):
python
import requests response = requests.post( "https://api.veryfi.com/api/v8/partner/documents/", cert=("client.crt", "client.key"), headers={ "CLIENT-ID": "YOUR_CLIENT_ID", "AUTHORIZATION": "apikey USERNAME:API_KEY", }, json={"file_url": "https://cdn.example.com/invoice.jpg"} )Node.js (https):
javascript
const https = require('https'); const fs = require('fs'); const agent = new https.Agent({ cert: fs.readFileSync('client.crt'), key: fs.readFileSync('client.key'), }); fetch('https://api.veryfi.com/api/v8/partner/documents/', { method: 'POST', agent, headers: { 'CLIENT-ID': 'YOUR_CLIENT_ID', 'AUTHORIZATION': 'apikey USERNAME:API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ file_url: 'https://cdn.example.com/invoice.jpg' }), });
What happens once mTLS is enforced
Once Veryfi enables mTLS on your account:
Any request that does not present a client certificate is rejected at the TLS handshake level, before it ever reaches the API layer.
Any request that presents a certificate not registered to your account is also rejected.
Requests with a valid certificate proceed normally and still require your standard API key headers (CLIENT-ID, AUTHORIZATION).
mTLS and API key authentication work together, not as alternatives to each other.
Certificate management
Topic | Guidance |
Certificate expiry | Certificates have a validity period. Rotate them before they expire or API calls will begin failing. |
Rotating a certificate | Generate a new cert/key pair, send Veryfi the new |
Multiple environments | If you use separate production and staging profiles, each profile can have its own registered certificate. |
Private key storage | Store your private key securely (e.g. in a secrets manager like AWS Secrets Manager or HashiCorp Vault). Never commit it to source control. |
What mTLS does not replace
mTLS is an additional layer, not a replacement for existing security practices. You still need to:
Keep your API_KEY and CLIENT_SECRET secret
Rotate your API Key on a regular schedule (key rotation guide)
Use HTTPS for all requests (always enforced by Veryfi)
Restrict API Key access to Admin team members only
Questions? Email [email protected] or chat live at app.veryfi.com.