Manage API credentials

Protect and rotate the API keys, OAuth client credentials, service account credentials, and access tokens your server uses to authenticate Tango API requests.

Before you begin

• Sign in to Tango portal and confirm your user has permission to manage Tango API keys under Integrations. Ask your portal admin to grant access if needed.
• Choose where your server will store credentials securely, such as a secrets-management solution. Keep sandbox and production credentials separate.
• Identify which integrations use each API key, OAuth client credential, or service account so you can update them during rotation.

Protect API credentials

1. Store secrets outside your source code: Treat API keys, OAuth client secrets, and service account passwords as sensitive credentials. Store them in your secrets-management solution rather than hardcoding them in your application.
2. Use credentials only from a trusted server-side environment. Do not make Tango API calls from a browser or expose credentials to client-side code. Tango does not support browser-based API requests.
3. Limit access to credentials. Do not send API keys, OAuth client credentials, service account passwords, or access tokens through email, chat, or other unsecured channels. Grant credential-management permissions only to users who need them.
4. Keep environments separate. Use sandbox credentials in sandbox and production credentials in production. Test credential changes in sandbox before updating production.

For additional guidance on protecting sensitive information, see OWASP Top 10: Cryptographic Failures.

Protect OAuth service accounts

OAuth service account usernames and passwords are authentication credentials and should be protected with the same level of care as API keys and OAuth client secrets. Store service account credentials in a secure secrets-management solution, restrict access to authorized personnel and systems, and avoid embedding credentials directly in application code or configuration files. Rotate service account credentials whenever compromise is suspected, when personnel with access leave the organization, or when creating new OAuth client credentials. OAuth authentication relies on the client ID, client secret, service account username, and service account password; all four credentials should be protected accordingly.

Rotate API credentials

Rotate API credentials at least every 90 days. Rotate immediately after a suspected or confirmed compromise or a personnel change involving access to credentials. Rotate after major API, system, or infrastructure changes, and rotate more frequently if your organization’s requirements call for it. Regular rotation limits how long a compromised credential can be used.

To rotate API credentials:

1. Create a replacement credential in Tango portal. For portal instructions, see Manage Basic Auth API keys in Tango or Manage OAuth client credentials in Tango. Tango supports up to two active Basic Auth API keys or two active OAuth client credentials at a time, allowing you to keep the existing credential active during the change.
2. Store the replacement securely and update your integration. Change the server-side configuration that supplies the credential. For OAuth, use the replacement client credentials when requesting a new access token.
3. Verify requests with the replacement. Test in sandbox before changing production. Confirm that your production integration authenticates with the replacement credential before removing the old one.
4. Deactivate the old credential. Remove it from your integration and secrets store after verification. Deactivation of Basic Auth API keys and OAuth client credentials cannot be undone; generate a new credential if you need another one later.

Optional: Manage OAuth service accounts and access tokens

OAuth authentication uses a client ID and client secret together with a service account username and password to acquire an access token. The service account password is visible only when you create the account: copy it immediately into secure storage. If you lose the password, delete the service account and create a new one. See Use OAuth for more secure connection for the portal and token-request steps.

Depending on the selected audience, an OAuth access token expires after 24 hours (86,400 seconds) or 5 minutes (300 seconds). Cache the token for its time-to-live (TTL), and obtain a new one before or when it expires rather than requesting a token for every API call. The token endpoint is limited to 100 transactions per second, and each service account is limited to 10 tokens per minute. See Acquire a service account token for token acquisition details.

When replacing a service account, obtain and test a token using the new account before deleting the old one. If you use OAuth with DPoP, protect its private key as well; follow that guide for proof and key requirements rather than treating a DPoP-bound token like a standard Bearer token.

Troubleshoot credential changes

• Authentication fails after rotation: Check that your server is using the new credential for the correct environment. For OAuth, request a new token using the updated credentials; an expired token must be replaced.
• You can’t retrieve a service account password: The password is only visible at creation. Create a replacement service account, update your integration, verify its token works, then delete the old account.
• You can’t create another active credential: Check whether you already have two active API keys or two active OAuth client credentials. Verify that the replacement works before deactivating an old credential to free a slot.
• You need help with a failed request: Share the X-REQUEST-ID from the response header with Tango support so they can locate the request. Do not send API keys, access tokens, service account passwords, or reward credentials in your support message. For how X-REQUEST-ID differs from an order’s externalRefID, see Best practices.

For credential or account assistance, contact your Tango representative or email [email protected].