Documentation

Use OAuth for secure connection

Suggest Edits

🚧

Closed Release

This feature is a Closed Release, available for a limited number of users and specific use cases only.

To take full advantage of our Tango API, we recommend you to use Open Authorization (OAuth) 2.0. OAuth establishes a secure connection with the Tango API using authorization tokens to verify your system’s identity. In order to create a token, you need four pieces of information: client ID, client secret, service account username, and service account password. See Acquire a token.
Once you acquire a token, you can use it to authenticate the Tango API connection. You can create as many tokens as you’d like. With OAuth 2.0, you can rotate your credentials with no downtime. See our API document to learn how you can Secure your connection with OAuth 2.0.


📘

Note:

  • We recommend you to rotate your client credentials once a year. Client credentials never expire.
  • We recommend you to rotate your service account frequently whenever your connection has been compromised, or when you’re creating new OAuth client credentials. Service accounts never expire.
  • The OAuth tokens are generated from OAuth credentials and expire in 24 hours (86400 seconds). Fetch a new token at least once every 24 hours to authenticate API calls. New tokens can be generated using the same client credentials and service accounts or the updated ones. See how to Acquire a new OAuth token.
  • You’re expected to manage your client credentials and service accounts. See Manage (new) OAuth 2.0 client credentials in Tango and Manage OAuth 2.0 service accounts in Tango.

How to use OAuth 2.0 to secure your connection?

Follow the instructions below to :

Step 1: Get your OAuth client credentials

To access client credentials, you must have Tango API keys Manage permissions enabled under the Integrations permission section of the user setup screen. If you’re not an admin, contact your Tango portal admin to give you permission. Learn how to Set user permissions and access level. See Set up work environment for Tango API.

To get your OAuth client credentials in Tango portal:

  1. Log in to the Tango portal. See how to Sign in to Tango portal.

  2. Go to Team settings > Integrations on the left menu.

  3. Click OAuth client credentials > Create Credentials.

  4. Copy Client ID and Client Secret and keep them safe.

  5. (Optional) Enter a Display name to identify the credentials later and click Save display name. New client credentials are generated and immediately accessible for use. Use these client credentials along with OAuth service account to acquire a token.

📘

Note:

  • Treat your OAuth credentials like passwords, never share them with unauthorized parties or over unsecure channels. Create a new OAuth client credential for your Tango platform whenever your client credentials have been compromised.
  • Deactivate the client credentials when you no longer use the API integration connected to your Tango platform.
  • You can have up to two active keys at the same time. You cannot reactivate client credentials, but you can generate a new credential and update the integrations that used the original credentials.
  • 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: Get your OAuth Service Account

Username and password are additional security layers in Tango API provided via OAuth Service Account in Tango portal. To create an authorization token for OAuth and verify your system’s identity, you’re required to have service account username and password besides client ID and client secret (OAuth client credentials).

📘

Note:

The service account password is only visible at the time of creation. Copy and paste the password directly in the code or keep it secure. Delete the Service Account and create a new one if the password is lost.

To get your OAuth Service Account in Tango portal:

  1. Log in to the Tango portal.

  2. Go to Team settings > Integrations on the left menu.

  3. Go to Apps > OAuth Service Accounts.

  4. Click Create service account.

  5. Copy Username and Password and keep them safe. Password is visible at the time of creation. Paste the values directly into your API code, or save it somewhere secure for later use. You will not be able to access this password again.

  6. (Optional) Enter a Display name to identify your service account later.

  7. Click Save display name (optional). New service account is generated and immediately accessible for use. Use the service account along with OAuth client credentials to acquire a new token.

Step 3: Acquire a new OAuth token

Use POST {URI}/oauth/token and the client ID, client secret, username, and password you have created in the Tango portal to send a request and acquire a new token. See Acquire a token for full instructions and details.

📘

Best Practices

  • Your service account password is only visible at the time of creation. We recommend you to save the password upon creation. You cannot recover this password again.
  • Tango API token can be refreshed at most once a day. We recommend you to save the token and utilize it until expires in 24 hours. Fetch a new token at least once every 24 hours to authenticate API calls. See how you can acquire a Tango access token.
  • Create a new service account and a new token using valid and existing service account. Then update your token and API call with the new service account credentials before deleting the old service account. Make sure the new tokens are generated and working before deleting the old service account. It can be done whether or not you cycle your client credentials.

Step 4: Test your integration

Once you get a new token, call the Tango API to establish the API connection. With OAuth 2.0, you can rotate your OAuth credentials with no downtime.

Test your connection in our developer's application and make API calls, such as getting a list of customers, get details for a specific credit card deposit, 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 test your integration:

  1. Open the API test console.

  2. Go to the API function you want to test, such as Get a list of all customers.

  3. Change CREDENTIALS from Basic to Bearer .

  4. Enter the token you have acquired above.

  5. Click Try it and check the response.

How to deactivate OAuth credentials?

You may want to deactivate OAuth credentials (client credentials or service accounts) for several reasons. Deleting service account cannot be reversed:

  • For security best practices—to cycle them regularly
  • To prevent harm— when your API has been compromised
  • To stay cautious—such as when people with access leave the company

To deactivate OAuth credentials:

  1. Log in to the Tango portal.
  2. Go to Team settings > Integrations on the left menu.
  3. Click the OAuth client credentials or OAuth Service Accounts and click the Deactivate button.

See more information in Manage (new) OAuth client credentials in Tango, or Manage (new) OAuth service accounts in Tango.

Updated 4 days ago

© 2025 Tango API are provided by Tango, a division of BHN, Inc.