Security and authentication best practices

All communication with the Tango API must be authenticated to verify the identity of the user attempting to connect to the server. Authentication credentials are included with each request to establish a trusted connection. For authentication account assistance, reach out to one of our Support specialists or email [email protected].

Authentication and authorization

Every request to the Tango API must be authenticated. This section covers the supported authentication methods and best practices for managing access to your platform.

Authenticate and handle client credentials

All API requests require the platform’s authentication credentials. Authentication credentials are sent using one of the following methods:

• OAuth 2.0 client credentials: Establish a secure connection using an access token obtained with your client ID and client secret.
• Basic Auth client credentials: Authenticate your connection using your platform name and API key.
• OAuth 2.0 with DPoP: For the highest level of security, add DPoP (RFC 9449) to bind your access token cryptographically to a client key pair. This method requires your platform to have DPoP enabled—contact your Tango representative.

Account-level access control responsibilities

Your platform is responsible for enforcing account-level access controls. For example, your application must prevent users associated with Account A from placing orders on behalf of Account B. Tango validates the identity of the calling platform but does not manage authorization between accounts within your platform.

Avoid browser-based API Calls

Tango APIs must be called from a trusted server-side environment. Browser-based API calls are not supported due to security risks. Attempts to do so will result in an authorization error (403.001) or Cross-Origin Resource Sharing (CORS) errors. CORS is a security feature that lets web pages request resources from a different domain. If you get CORS errors, your integration is likely attempting browser-based API calls. CORS failures are not limited to POST requests. As a best practice, we highly recommend using non-browser tools for all API calls.

Credential security

Protecting authentication credentials is critical to maintaining a secure integration. This section covers best practices for storing, managing, and rotating API keys, client secrets, and other sensitive credentials used to access the Tango API.

Protect platform keys

Treat API keys, client secrets, and other credentials as sensitive information. Never transmit your platform API keys and client credentials via email, chat, or any other unsecured method. Store credentials in a secure secrets-management solution and design your systems to support routine credential rotation. Rotate credentials immediately following a suspected compromise or a personnel change involving users with access to sensitive credentials.

The OAuth tokens are generated from client credentials and expire in either 24 hours (86,400 seconds) or 5 minutes (300 seconds), depending on the selected audience. Keys are managed through Tango portal. See how to get the client ID and secret from Tango . For more information on industry best practices in this area, see OWASP Top 10, #2

Rotate API credentials

The following recommendations are taken from ElevateAI as the general industry's suggestion:

• While industry guidance commonly recommends rotating credentials every six months, Tango recommends rotating API credentials at least every 90 days. Increase frequency when required by your compliance requirements and risk profile.
• Immediately after any suspected or confirmed compromise
• After personnel or system changes
• After major API or infrastructure updates
  The specific frequency will depend on your risk profile. More sensitive applications and data may warrant more frequent rotations, while less critical systems could go a year or longer between refresh cycles.

DPoP security

Demonstration of Proof-of-Possession (DPoP) enhances OAuth security by binding access tokens to a client-controlled cryptographic key. This section outlines the requirements and best practices for securely generating, storing, and using DPoP keys and proofs.

Handle DPoP keys and proofs securely

If your platform uses DPoP, follow these additional requirements:

✅ Store your DPoP private key in an HSM, secure enclave, or encrypted secrets manager (e.g., AWS Secrets Manager, Azure Key Vault). Never log or transmit it.

✅ Generate a fresh jti UUID for every DPoP proof—proofs cannot be reused.

✅ Include the ath claim (base64url SHA-256 of the access token) in all API call proofs.

✅ Keep your system clock synchronized via NTP—the server enforces a ±60-second tolerance on proof timestamps.

❌ Do not include private key material in the jwk header of your proof—public key only.

❌ Do not use Authorization: Bearer with a DPoP-bound token—use Authorization: DPoP.

❌ Do not include query strings in the htu claim—use scheme + host + path only.

❌ Do not reuse DPoP proofs across requests, even for the same endpoint.

Secure API requests

Secure API integrations require more than authentication alone. This section describes best practices for validating request content, preventing malicious or malformed payloads, and building resilient integrations that can safely handle network failures and retry scenarios.

Prevent injection-style payloads and malicious behavior

Tango may reject requests based on content or behavior that could be exploitative. It includes requests containing insecure characters or inconsistent with OWASP guidelines. See A03:2021 – Injection for reference.

Configure timeouts and incremental retries

Network errors are inevitable due to unpredictable conditions, infrastructure limitations, and supplier factors. Your system should be designed to handle these scenarios. Configure client timeouts to wait at least 15 seconds for a response before considering the request failed.

To prevent duplicate orders during retries or transient network failures, use a unique externalRefID for every transaction. This enables idempotent request handling and helps avoid accidental duplicate submissions.

Additionally, as a best practice, implement an exponential backoff or similar retry algorithm, where the wait time increases after each failed attempt. Ensure that each retry attempt also maintains the connection for the full 15 seconds before timing out.

Transport security

Transport security protects data while it is transmitted between your systems and the Tango API. The following guidance explains how to validate server identities, establish trusted TLS connections, and ensure your application can correctly verify certificate chains.

Use a complete certificate chain

Use a complete certificate chain, including SSL/TLS and Certificate Authority (CA), to authenticate requests to the Tango API:

SSL/TLS certificate

Communication with the Tango API is handled via Transport Layer Security (TLS), a widely used protocol for secure message transmission over the Internet. Ensure your runtime trust store can validate the server certificate chain (root/intermediate CAs). In most environments, default OS/runtime trust stores already handle this; provide a custom CA bundle only when your environment requires it. To accomplish this, we recommend adding the Certificate Authority (CA) to your system’s trusted list. If that’s not possible, you can include the certificate in your application. Major CAs deliver a bundled file containing the complete certificate chain, providing a single installation method for the certificate.

Certificate authority (CA)

Tango uses Amazon Web Services (AWS) to create our SSL certificates. You can get AWS’s root and intermediate certificates from AWS Docs: Server Authentication Certs. If you choose to reference the certificate chain from your application’s code, the details on how to do this are highly specific to the library being used to make the connection.

Examples

The following examples demonstrate how to configure TLS certificate validation in common programming languages and HTTP clients. Use these examples as a reference when establishing secure connections to the Tango API and verifying server certificates.

Example 1: Configure SSL certificate verification in Ruby

This example shows how to configure a Ruby HTTP client to use SSL/TLS securely when calling the Tango API. It enables SSL, verifies the server’s certificate using a trusted CA file (AmazonRootCA1.pem), and then makes a secure GET request:

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: Configure SSL certificate verification in PHP

This example demonstrates how to use PHP’s cURL library to make a secure HTTPS request to the Tango API. It enables SSL certificate verification and specifies a trusted CA file (AmazonRootCA1.pem) to ensure the server’s identity is validated before the request is executed:

$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: Use default SSL certificate in Python

This example shows how to make a secure HTTPS request using Python’s requests library, which verifies SSL certificates by default. It also highlights best practice by using secure credential handling (such as environment variables) instead of hardcoding sensitive information:

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))

Advanced security controls

Advanced security controls provide additional layers of protection beyond standard authentication and transport security. The following features help restrict access to trusted clients and networks, reducing the risk of unauthorized access to the Tango API.

Security layers overview

Tango supports multiple security controls that can be used independently or together to provide defense-in-depth.

Mutual TLS (mTLS)

Mutual Transport Layer Security (mTLS) is an optional, platform-level security enhancement that adds
certificate-based authentication at the transport layer. It is not a replacement
for Basic Auth or OAuth—your existing credentials are still required. mTLS works
alongside your chosen authentication method to ensure that only clients presenting a
trusted certificate can reach the Tango API, before any application-layer
credential check occurs.

mTLS is designed for enterprise customers with elevated security requirements. Contact
your Tango representative or email [email protected] to have mTLS enabled for your platform.

How mTLS works

When mTLS is enabled for your platform, requests must be sent to a dedicated mTLS
endpoint. At that endpoint, Tango's edge layer performs a mutual TLS handshake:
both the client (your system) and the server (Tango) present and validate certificates
before the request is forwarded to the API. If the client certificate is missing, expired,
revoked, or untrusted, the connection is rejected at the edge — before any application
processing occurs.

The following table shows mTLS endpoints:

Enable mTLS for your platform

mTLS is disabled by default and must be enabled by your Tango representative at the platform level.

To enable mTLS for your platform:

1. Contact your Tango representative or email [email protected]
   to request mTLS enablement.
2. Provide your public key (X.509 certificate) to Tango for trust configuration. Tango will provide its public
   key in return so that the mutual handshake can occur.
3. Update your integration to use the mTLS endpoint (see mTLS table above) and include your
   client certificate on every request.
4. Test in the sandbox environment before enabling in production.

   📘

   Note:

   Once mTLS is enabled for your platform, calls to the standard (non-mTLS) endpoint
   will be rejected—even if your API credentials are valid. Before your Tango
   representative enables mTLS, verify that your integration is fully updated to use
   the mTLS URI.

Certificate requirements

Tango accepts the following client certificate types:

• RSA – 2048-bit minimum
• ECDSA – P-256 minimum

Additional requirements:

• Maximum certificate validity: 1 year
• Certificates must be X.509 format
• Certificates may chain to a BHN-managed Certificate Authority (CA) or be
  customer-managed certificates accepted under the approved trust model
• Revoked, expired, or untrusted certificates are rejected during the TLS handshake

mTLS checklist

✅ Continue sending your Basic Auth credentials, OAuth Bearer token, or DPoP-bound access token on every request.

✅ Use the mTLS-specific endpoint (mtls.tango-api.bhn.com in production,
mtls.sandbox-tango-api.bhn.com in sandbox).

✅ Present a valid X.509 client certificate meeting the key type and validity requirements
on every request.

✅ Plan and test certificate rotation before your current certificate expires — an expired
certificate will cause all requests to fail at the edge.

✅ Test in sandbox before enabling mTLS in production.

❌ Do not use the standard Tango API endpoint (api.tangocard.com) once mTLS is enabled
for your platform — requests will be rejected.

❌ Do not treat mTLS as a substitute for securing your API keys or OAuth credentials.
Both layers of security must be maintained.

Use mTLS with other security features

mTLS is independent and can be combined with other security enhancements:

• OAuth 2.0 with DPoP – Adds cryptographic proof-of-possession at the application
  layer. See Secure API requests with OAuth DPoP.
• IP allowlist – Restricts inbound traffic to approved IP ranges. This is managed
  separately from mTLS; contact your Tango representative for details.

Using mTLS together with DPoP and an IP allowlist provides defense-in-depth across
the network, transport, and application layers.

IP allowlist

An IP allowlist is an optional, platform-level security enhancement that restricts
Tango API access to requests originating from approved IP addresses or CIDR ranges.
It is not a replacement for Basic Auth, OAuth, or DPoP — your existing credentials are
still required. The IP allowlist works alongside your chosen authentication method
to enforce a network-layer control before any application-layer credential check
occurs.

The IP allowlist is designed for enterprise customers with elevated security or
compliance requirements. Contact your Tango representative or email
[email protected] to have an IP allowlist enabled for your platform.

How IP allowlists work

When an IP allowlist is enabled for your platform, every inbound Tango API request
is evaluated against the configured list of allowed IP addresses and CIDR ranges.
This check occurs before Tango API endpoints are executed.

If the source IP matches an allowed entry, the request proceeds normally.
If the source IP does not match, the request is rejected before any further
processing occurs.

The IP allowlist is platform-scoped — it applies to all Tango API endpoints for the
enabled platform.

Enable an IP allowlist for your platform

The IP allowlist is disabled by default. It is controlled by a platform-level
setting that your Tango representative configures in the Tango administrative system.

To enable IP allowlist for your platform:

1. Contact your Tango representative or email [email protected] to request IP allowlist enablement.
2. Provide the IP addresses and/or CIDR ranges that should be permitted. These are
   typically your organization's known egress IPs. Both individual IPv4 addresses
   and IPv4 CIDR ranges are supported.
3. Test in the sandbox environment before enabling in production.

Error responses

Requests blocked by IP allowlist enforcement return an authorization error. The
response indicates that access was denied due to IP restrictions without exposing
your IP allowlist configuration or revealing which addresses are approved.

Blocked requests are logged with the source IP, platform, timestamp, and denial
reason, and are available to Tango support and operations for troubleshooting.

IP allowlist checklist

✅ Continue sending your Basic Auth credentials, OAuth Bearer, or DPoP token on
every request — the IP allowlist does not replace application-layer authentication.

✅ Provide all known egress IP addresses and CIDR ranges before requesting activation
— a missing entry will block your integration.

✅ Account for all systems that call the Tango API, including proxies, middleware,
and API gateways. The source IP evaluated is the IP the request arrives from at
Tango's edge — ensure that IP is included in your IP allowlist.

✅ Plan for IP changes. If your egress IPs rotate or change, contact your Tango
representative to update your IP allowlist before the change takes effect.

✅ Test in sandbox before enabling in production.

❌ Do not treat the IP allowlist as a substitute for securing your API keys or
OAuth credentials. Both layers must be maintained.

❌ Do not assume the IP allowlist will prevent all unauthorized access on its own —
it restricts by network origin only. Credential-based authentication still applies.

Use an IP allowlist with other security features

The IP allowlist is independent and can be combined with other security enhancements:

• OAuth 2.0 with DPoP — Adds cryptographic proof-of-possession at the
  application layer. See Secure API requests with OAuth DPoP.
• Mutual TLS (mTLS) — Adds certificate-based authentication at the transport
  layer. See Enhance your connection with Mutual TLS (mTLS).

Using an IP allowlist together with mTLS and DPoP provides defense-in-depth across
the network, transport, and application layers.

Proxy and middleware configuration

Many integrations connect to the Tango API through proxies, middleware platforms, or API gateways. This section describes common configuration issues that can affect request processing and provides guidance for troubleshooting connectivity and authorization errors.

Configure proxy and middleware system

Integrations that route requests to the Tango API through a proxy or middleware layer—such as Azure Integration Service (AIS), Azure API Management, MuleSoft, or any other API gateway—may receive a 403 Forbidden response even when the request is otherwise valid and properly authenticated.

The Tango API is served behind an AWS Application Load Balancer (ALB). The ALB enforces request validation rules for X-Forwarded-For (XFF) and expects IP-only values (no port suffix). Note that RFC 7239 defines the standardized Forwarded header format, while X-Forwarded-For is a de facto header used by many proxies/load balancers.

Avoid non-standard XFF header formats

Many proxy and middleware systems—including certain configurations of Azure Integration Service, Azure API Management, and Salesforce outbound calls—automatically append an XFF header that includes both an IP address and a port number. This results in a non-compliant format:

// Non-standard format  (triggers 403)
X-Forwarded-For: 203.0.113.42:54321

When the ALB receives an XFF header value that does not conform to the IP-only format, it rejects the request at the infrastructure layer before it reaches the Tango application. This is why the response body is HTML rather than JSON, and why the server header identifies the load balancer (awselb/2.0) rather than the API service.

Verify the cause

Before applying the fix, verify that XFF header formatting is the cause:

1. Capture the outgoing HTTP headers from your proxy or middleware layer.
2. Look for an X-Forwarded-For header. If the value is in ip:port format, this article applies.
3. To reproduce explicitly, send the same request with the XFF header manually set to an IP:port value. You should receive a 403. Then strip the port—you should receive a 200 OK.

Resolve Non-Standard XFF Header Issues

The fix is to ensure that the X-Forwarded-For header sent to Tango contains only a well-formed IP address, with no port suffix. The method for doing this depends on your middleware platform.

<set-header name="X-Forwarded-For" exists-action="override">
    <value>{{YOUR_OUTBOUND_PUBLIC_IP}}</value>
</set-header>