Authenticate with API

Overview here (What is authentication and why need to authenticate?)
.
.
.

All communication with Tango Card’s RaaS API must be authenticated. We recommend Certificate Chain certificates containing SSL/TLS and Certificate Authority (CA) for authentication:

About SSL/TLS Certificate

The communication with Tango Card’s RaaS API is handled over Transport Layer Security (SSL), a commonly-used protocol for managing secured message transmissions on the Internet. As a client of the RaaS 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.

About Certificate Authority (CA)

Tango Card 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: 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: 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: 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 it is that you’re talking to.

Authenticate and Handle Credentials

All calls require the platform’s authentication credentials. Authentication credentials are sent using HTTP Basic auth with the platform name as the username and the platform access key as the password. Username and password are assigned by Tango Card.

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

Tango Card only provides Platform Keys via secure methods such as Dashlane or Lastpass. Never email platform keys or store them on a shared drive.

Cross-site Scripting (XSS) and Malicious Behavior

Tango Card may reject requests based on content or behavior that can be exploitative in nature. This includes requests containing insecure characters or not consistent with OWASP Top 10 guidelines.

Protect Platform Keys

Never transmit your platform keys 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. Rotating to new keys on a schedule is also advisable, keys are managed through the Reward Genius Web Application.

For more information on industry best practices in this area see OWASP Top 10, #2

Timeouts and Incremental Retry

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

Additionally, we strongly recommend that you build an exponential backoff or similar retry algorithm in which the timeout value for retry increases after each unsuccessful attempt.


What’s Next