To take full advantage of our Tango API resources without security concerns, we recommend you to establish a secure connection to the Tango API.

We support the following methods to add security to the Tango API:

• Open Authorization (OAuth) 2.0—OAuth asks your permission and access rights without sharing your password data. It's more about authorization than authentication using authorization tokens to verify your identity.
• Basic Authentication —Basic Auth is all about authentication; it proves you’re the correct person with the online account credentials. Basic Auth requires your credentials to gain access to your platform.

📘

Note:

Tango API OAuth 2.0 is currently available on a limited release. Contact your Customer Success Manager (CSM) or [email protected] to have this feature added to your production account or for more information.

OAuth authorization provides:

• the most secure connection while keeping your credentials safe.

• the ability to rotate credentials with no downtime.

  

Secure your connection with OAuth 2.0

You must first retrieve your client credentials for OAuth by going to the Tango portal. See how to Sign in to the Tango portal . If you don't have an account with Tango, see how to set up an account . With client credentials ready, acquire a token and call the Tango API. See how you can acquire a Tango access token

• Step 1: Retrieve your client credentials from Tango
• Step 2: Acquire a token
• Step 3: Call Tango API

📘

Note:

• You are expected to manage your own client credentials using the Tango portal. Client credentials do not expire.
• The OAuth tokens are generated from client credentials and expire in 24 hours (86400 seconds).
• Acquire a new token by reissuing the POST {URI}/oauth/token request using your client credentials.
• Request for new tokens are rate limited to one per 20 hours.
• Failure to comply with rate limit will result in a 400 error message: "Client {internal client_name} {client id} has exceeded the daily rate limit".

❗️

Caution about rate limit

Use a distributed cache to store the token so that upon a restart the token can be retrieved without having to create a new token and hitting the rate limit. Only renew the token if it's been expired or within the four (4)-hour refresh window.

Step 1: Retrieve you client credentials from Tango

1. Log in to the Tango portal.
2. Go to Team settings on the left menu.

3. Click Manage under OAuth client credentials.

4. Click Generate Client Credentials to generate the Client ID and Client Secret.

📘

Note:

You can generate up to two credentials at a given time and deactivate a credential if it's no longer required. It provides an option for you to rotate credentials when needed. For security reasons, you're encouraged to rotate your credentials periodically.

5. Check out Audit Log to view the history of activities in managing the credentials, and for audit purposes.

Step 2: Acquire a token

Use the client ID and client secret you have generated in the Tango portal and send a request to {URI}/oauth/token.

📘

Note:

The following URLs links take you to the /token endpoint:

• Sandbox: https://sandbox-auth.tangocard.com/oauth/token
• Production: https://auth.tangocard.com/oauth/token

We recommend you to try the Tango API test console first. Follow the instructions below:

To acquire a token:

1. Go to the Tango API test console.
2. Use the Client ID and Client Secret you generated in the Tango portal.
3. Send a POST request to the {URI}/oauth/token endpoint replacing YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your client credentials.

See the example request below:

curl --request POST \
  --url 'https://sandbox-auth.tangocard.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data "grant_type"="client_credentials" \
  --data "client_id"="YOUR_CLIENT_ID" \
  --data "client_secret"="YOUR_CLIENT_SECRET" \
  --data "audience"="https://api.tangocard.com/"
  --data "scope"="raas.all"

4. Get the OAuth token from the above API call. The response is in JSON format and is presented under the field named access token.

See an example response below:

{
"access_token": "eyJhdgskjgfdspoeufeopfu",
"expires_in": 2592000,
"token_type": "Bearer"
}

5. Save the token in your database.

📘

Note:

Tango API token can be refreshed at most once a day. As a best practice, we recommend you to save the token and utilize it until it expires in 24 hours.

See the example request below:

    
     curl --request POST \
     --url https://sandbox-auth.tangocard.com/oauth/token \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data "client_id"="string" \
     --data "scope"="raas.all" \
     --data "audience"="https://api.tangocard.com/" \
     --data "grant_type"="client_credentials" \
     --data "client_secret"="string"

Here are a couple of examples of response payload you may receive:

{
  "access_token": "string",
  "scope": "string",
  "expires_in": 0, (in seconds)
  "token_type": "Bearer"
}

or

{
  "access_token": "string",
  "scope": "raas.all",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Step 3: Call Tango API

Use the token retrieved above to make Tango API calls such as getting a list of customers, get details of accounts, etc. See an example request below:

curl \
    --header "Accept: application/json" \
    --header "Authorization: Bearer YOUR_TOKEN_HERE" \
    https://integration-api.tangocard.com/raas/v2/customers

In the Test Console

1. In the Tango API test console, navigate to a Tango API function you want to test, such as Customers.
2. Change Basic to Bearer under AUTHENTICATION.
3. Enter your token.
4. Click Try it and check the response.

Secure your connection with Basic Auth

In Basic Auth, the API key and platform name are used for authentication with the Tango APIs. To start, log in to your Tango portal and get your platform name and generate the API key. Encode your platform name and API key in base64 and use it for authentication. See how to Sign in to our Tango portal . If you don't have an account with Tango, see how to set up an account . See our great API endpoints.

👍

Best practice:

We recommend only one active key at a time. Rotate your API Keys at least every six months AND whenever someone who's had access to the key leaves the company. To avoid disruption when you rotate the keys, you can have two active keys at a time.

• Step 1: Get the platform name and generate the API key
• Step 2: Call the Tango API
• Step 3: Try it in test console

Step 1: Get the platform name and generate the API key

1. Sign in to the Tango portal.
2. Navigate to Team settings on the left menu.

3. Go to RaaS API keys and click Manage.

4. Click Generate API Key to create a new API key.
5. To make the key visible, click the eye icon next to your Active key.
6. To Copy, hover with your mouse on top of the API Key and click.

Step 2. Call the Tango API

Use the platform name and API key to call the Tango API

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://integration-api.tangocard.com/raas/v2/customers")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Basic YOUR_API_KEY")
  .build();

Response response = client.newCall(request).execute();

Step 3: Try it in test console

1. In the Tango API test console, navigate to a Tango API you want to test such as Customers.
2. Select Basic under AUTHENTICATION.

1. Enter your platform name for the username, and enter your API key for the password.
2. Click Try it and check the response.

For questions and more information, email us at [email protected].