Documentation

Dos and Don'ts: Security and authentication

Suggest Edits

All communication with Tango API must be authenticated. The API authentication process validates the identity of the user attempting to connect to the server. The authentication protocol sends credentials from the remote user requesting access to the server. For an authentication account, reach out to one of our Technical Support specialists or email [email protected].

Authenticate and handle client credentials

All calls require the platform’s authentication credentials. Authentication credentials are sent using HTTP Basic Auth or OAuth 2.0 in Tango portal:

  • OAuth 2.0 client credentials: Allows you to establish a secure connection with API via an authorization token which uses your client ID and client secret.
  • Basic client credentials: Allows you to authenticate your connection with API using your platform name and API key.

The platform is responsible for handling access to its accounts such as not allowing ACC1 to place an order using ACC2 account. Requests from authenticated platforms against their accounts are implicitly trusted.

📘

Note:

Tango only provides API keys or client credentials. See Find and manage API keys in Tango and Find and manage OAuth 2.0 client credentials.

Avoid browser-based API Calls

We do not allow browsers to POST calls. Attempts to do so, will result in an authorization error (403.001).
For best practices, we highly recommend to use non-browser tools for all API calls.

Protect platform keys

Never transmit your platform keys or client credentials via email or any other unsecured method. Design your system to allow for routine key changes. Change your keys immediately when employees who had access to the keys leave. If you suspect any suspicious activity on your platform, change your keys. We recommend to rotate to new keys on a schedule. The OAuth tokens are generated from client credentials and expire in 24 hours (86400 seconds). keys are managed through Tango portal. See how you can get client ID and secret from Tango. For more information on industry best practices in this area see OWASP Top 10, #2

How often should you refresh your API keys?

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

  • At least every six months – Rotating twice per year ensures keys don’t remain active for too long.
  • With significant personnel/system changes – If developers, admins, or integrated systems that use the keys change, rotate the keys.
  • After any known or potential compromises – If a key may have been exposed, generate a new one immediately.
  • With extensive API changes – Big updates to API functionality may warrant issuing new keys.
    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.

Cross-site scripting (XSS) and malicious behavior

Tango may reject requests based on content or behavior that can be exploitative in nature. It includes requests containing insecure characters, or requests that are not consistent with OWASP guidelines. See A03:2021 – Injection for reference.

Timeouts and Incremental Retry

Network unpredictability, infrastructure, and supplier factors are occasional network errors and must be planned for. We recommend holding the connection open 15 seconds before terminating a call with no response.

We STRONGLY recommend that you utilize the idempotent "externalRefID" field to prevent the accidental duplication of orders.

Additionally, best practice is to build an exponential backoff or similar retry algorithm in which the timeout value for retry increases after each unsuccessful attempt. Please ensure that all retry attempts hold the connections open for 15 seconds before terminating the call.

Recommended certificates

For Tango API, we recommend Certificate Chain containing SSL/TLS and Certificate Authority (CA) for authentication:

* SSL/TLS Certificate
The communication with Tango API is handled over Transport Layer Security (SSL), a commonly-used protocol for managing secured message transmissions on the Internet. As a client of Tango API, make sure you have the Certificate Chain (an intermediate certificate) on you server. Not having the Certificate Chain disallows communication and can expose you to the potential man-in-the-middle attacks. To accomplish this purpose, we recommend you to add the Certificate Authority (CA) to your system’s trusted list. If that’s not possible, the alternative is to 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, but here are a few examples to demonstrate the idea:

Example 1: SSL for Ruby language 

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: SSL for PHP language 

$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: SSL for Python language 

import requests
from requests.auth import HTTPBasicAuth
# SSL verify-peer is used by default.
requests.get('https://integration-api.tangocard.com/fake/example', auth=HTTPBasicAuth(username, password))

Please note that in the Ruby and PHP examples OpenSSL is being instructed to “VERIFY PEER”. This setting is essential as without it you know that your communication is encrypted, but you don't know who you’re talking to.

Updated about 1 month ago

What’s Next