Configure TLS and mTLS

Verify Tango’s TLS server certificate and, if enabled for your platform, connect to Tango API using mutual TLS (mTLS).

Transport Layer Security (TLS) protects data in transit and lets your client verify the server it connects to. Mutual TLS (mTLS) additionally requires your client to present a certificate. mTLS is optional and does not replace Basic Auth, OAuth, or OAuth with DPoP: authenticate every API request using your existing method.

Before you begin

• Set up server-side authentication using Basic Auth or OAuth 2.0.
• Confirm that your HTTP client verifies the server certificate using your operating system or runtime trust store. Do not disable certificate verification.
• If you plan to use mTLS, contact your Tango representative or email [email protected] to request platform-level enablement before switching endpoints.

Verify Tango’s server certificate

1. Enable TLS certificate verification in your HTTP client: Your client must validate the server’s certificate chain, including the intermediate and root certificate authorities (CAs). Default operating system and runtime trust stores handle this in most environments.
2. Use a custom CA bundle only if your environment requires one: Tango uses AWS certificates. If your trust store does not contain the necessary CA certificates, consult AWS server authentication certificates and configure your HTTP client’s trust store with the appropriate chain.
3. Test a server-side authenticated request: Confirm that the TLS handshake succeeds and your HTTP client receives an API response. If certificate verification fails, inspect the trust store and certificate chain rather than bypassing verification.

TLS verification examples from the original guide

These original snippets illustrate certificate verification in Ruby, PHP, and Python. They are not complete, runnable API requests: /fake/example is a placeholder path, the Ruby and PHP snippets assume a local AmazonRootCA1.pem file, and the Python snippet assumes username and password have already been defined. Use an actual endpoint, valid credentials, and the CA configuration your environment requires when implementing a request. Successful TLS verification establishes a connection; it does not guarantee a successful API response.

Example 1: Ruby

use_ssl = true enables HTTPS, and OpenSSL::SSL::VERIFY_PEER makes Ruby reject an untrusted server certificate. ca_file points to a local CA certificate file for verification; request_get then sends a GET request to the placeholder path.

https = Net::HTTP.new('integration-api.tangocard.com', 443)
https.use_ssl = true
https.verify_mode = OpenSSL::SSL::VERIFY_PEER
https.ca_file = File.join(File.dirname(__FILE__), "../ca_certs/AmazonRootCA1.pem")
https.request_get('/fake/example')

Example 2: PHP

The cURL client connects to the sandbox host. CURLOPT_SSL_VERIFYPEER enables server-certificate verification, CURLOPT_CAINFO selects a local CA file, and curl_exec() sends the request. Check the CA file path before using this snippet: as written, __DIR__ . "../ca_certs/AmazonRootCA1.pem" does not insert a directory separator after __DIR__.

$curl = curl_init('https://integration-api.tangocard.com/fake/example');
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($curl, CURLOPT_CAINFO, __DIR__ . "../ca_certs/AmazonRootCA1.pem");
curl_exec($curl);

Example 3: Python

Python's requests library verifies the server certificate by default, so no separate verification setting appears here. HTTPBasicAuth(username, password) supplies API credentials for the GET request; define those values in secure configuration before running the code.

import requests
from requests.auth import HTTPBasicAuth
# SSL verify-peer is used by default.
# Load credentials from secure configuration (env vars/secrets manager), not hardcoded values.
requests.get('https://integration-api.tangocard.com/fake/example', auth=HTTPBasicAuth(username, password))

In Ruby and PHP, enabling peer verification prevents the client from accepting an untrusted server certificate. Python's requests verifies server certificates by default. If verification fails, check your trust store and certificate chain; do not disable verification to make the request succeed.

Optional: Enable mTLS

mTLS is designed for enterprise customers with elevated security requirements. When enabled, Tango’s edge validates your client certificate during the TLS handshake before the API processes the request. A missing, expired, revoked, or untrusted certificate causes the connection to be rejected before application-layer authentication. Use the dedicated host for your environment:

1. Request enablement. Contact your Tango representative or [email protected]. mTLS is disabled by default and enabled at the platform level by Tango.
2. Exchange public certificates with Tango. Provide Tango with your public X.509 certificate for trust configuration. Tango will provide its public key in return so the mutual TLS handshake can occur. Keep your corresponding private key secure; do not send it with the public certificate. Coordinate certificate trust details with your Tango representative.
3. Update your server-side integration. Point requests to the mTLS host for the environment and configure your HTTP client to present the client certificate on every request. Continue sending your Basic Auth credentials, OAuth Bearer token, or DPoP-bound token as appropriate.
4. Test in sandbox before production. Verify both the TLS handshake and an authenticated API response with the sandbox mTLS host. Update every caller to use the mTLS host before production enablement; once mTLS is enabled for your platform, requests to the standard non-mTLS endpoint are rejected even if the API credentials are valid.

Client certificate requirements

Before you exchange your client certificate with Tango, check that it meets the format, key-strength, validity, and trust requirements in the following table. A certificate that does not meet these requirements cannot be used for the mTLS handshake.

Tango accepts the following client certificate types:

Plan and test certificate rotation before the current certificate expires. An expired, revoked, or untrusted client certificate prevents requests from passing the TLS handshake.

Check the connection

• TLS handshake succeeds and the API responds: Your client reached the API. Check the response using your normal authentication and error-handling flow.
• Handshake fails: Check the mTLS host, client certificate, private key, certificate validity, and trust configuration. A handshake failure happens before the API can return a normal application response.
• Standard API host rejects requests after mTLS enablement: Confirm that every caller, including proxies and middleware, uses the appropriate mTLS host.
• API rejects authentication after a successful handshake: Check the Basic Auth credentials or OAuth token separately. mTLS authenticates the client at the transport layer but does not replace API authentication.

mTLS rollout checklist

Before enabling mTLS in production, confirm that you have:

• Updated every caller to use the mTLS host for its environment, including proxies and middleware. Do not use the standard API host after mTLS is enabled.
• Configured every caller to present a valid X.509 client certificate on each request and planned certificate rotation before it expires.
• Kept Basic Auth credentials, an OAuth Bearer token, or a DPoP-bound token on every API request.
• Tested both the TLS handshake and an authenticated API response using the sandbox mTLS host.

mTLS can work alongside OAuth with DPoP and an IP allowlist. DPoP adds proof-of-possession at the application layer, while an IP allowlist restricts network access to approved source IPs. Configure each control separately, and continue authenticating every API request.