Documentation

Secure your connection with OAuth 2.0

Suggest Edits

Open Authorization 2.0 or OAuth 2.0 is a secure way to call API. Unlike Basic authentication, OAuth asks for your Client ID and Client Secret to establish a secure connection with API without sharing your password data. OAuth is more about authorization than authentication. It uses authorization tokens to verify your identity. Retrieve your client credentials for OAuth in the Tango portal. With client credentials, acquire a token and call the Tango API.

📘

Note:

  • Tango API OAuth 2.0 is currently available on a limited release. Contact your Customer Success Manager (CSM) or [email protected] for more information, or to have this feature added to your production account.
  • You must have Integrations as well as Manage Tango API keys permissions in Tango portal to retrieve client credentials. Learn how to Set user permissions and access level.

Follow the instructions below:


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 .

📘

Note:

  • You are expected to manage your own client credentials using the Tango portal. Client credentials do not expire. The OAuth tokens, however, are generated from client credentials and expire in 24 hours (86400 seconds).
  • Even though the credentials do not expire, an access token can only be used for 24 hours once created. Make sure to fetch a new token at least once every 24 hours to authenticate calls. See how you can acquire a Tango access token.

❗️

Rate limit

Request for new tokens are rate limited to one per 20 hours. Failure to comply with rate limit will result in this 400 error message: "Client {internal client_name} {client id} has exceeded the daily 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 your client credentials from Tango

With the Integrations and Manage Tango API keys permissions, you can access OAuth client credentials in the Tango portal and use it in your API integration. Be mindful of production vs. sandbox environment. Tango allows API developers to test using a sandbox environment before going live. See Set up work environment for Tango API.

To retrieve client credentials from Tango:

  1. Log in to the Tango portal.

  2. Go to Team settings > OAuth client credentials on the left menu.

  3. Copy Client ID. Hover on the ID and click to copy it to your clipboard.

  4. Copy Client Secret. Click the eye icon next to the Client Secret to reveal. Copy it to your clipboard and click the eye icon again to hide the Client Secret.

  5. Paste the Client ID and Client Secret in client_id and client_secret to acquire a token. See our test console regarding Acquire a token.
    Audit log shows when the client credentials are created or deactivated. The audit log also keeps a record of the users viewed and copied an API Key.

📘

Note:

  • Treat your client secret like passwords, never share them with unauthorized parties or over unsecure channels.
  • 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.

Step 2: Acquire a token

Use the client ID and client secret you have generated in the Tango portal and send a request to POST {URI}/oauth/token to acquire a new token. When you POST request to the {URI}/oauth/token endpoint, you replaceYOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your client credentials.

The following URLs take you to the /token endpoint, but we recommend you to try in the Tango API test console first:


To acquire a token:

  1. Go to the Tango API test console.

  2. Paste the Client ID and Client Secret you generated in the Tango portal in their respective fields: client_id and client_secret.

  3. Click Try it to acquire the token.

Get the OAuth token from the API call. Here's an example:

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"

The response is in JSON format and is presented under access token. Here's an example:

{
"access_token": "eyJhdgskjgfdspoeufeopfu",
"expires_in": 2592000,
"token_type": "Bearer"
}
  1. Save the token in your database for later use when you call Tango API to get some information such as list of customer, accounts, etc..

📘

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 for a specific credit card deposit, 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

To call Tango API:

  1. Navigate to a Tango API function you want to test, such as Customers. We recommend you to try in the Tango API test console first:

  2. Change AUTHORIZATION from Basic to Bearer .

  3. Enter your token.

  4. Click Try it and check the response.


Deactivate client credentials

You can deactivate an OAuth client credential for several reasons:

  • A security best practice—to cycle them regularly
  • To prevent harm— you think your API has been compromised
  • To stay cautious—when people with access leave the company

To deactivate client credentials:

  1. Sign in to Tango portal.
  2. Click Team settings > OAuth client credentials.
  3. Click Deactivate Client Credentials.
    You will receive a warning asking you to acknowledge that deactivating client credential may break your API integration until you updated with your new credential.
  4. Click to acknowledge, then Deactivate to confirm. A record of deactivated client ID can be seen in the Audit log.

📘

Note:

When you deactivate a client credential, all active tokens for this client will become invalid and your integration will be broken. Deactivation cannot be reversed.


Updated about 1 month ago

What’s Next