Nango ensures that API credentials are managed efficiently, with automatic refreshes for OAuth tokens and validity checks for API keys and basic credentials. This guide explains how Nango handles credential refreshes and failure scenarios.

​

OAuth credentials

​

Token refresh behavior

OAuth credentials are refreshed upon request, but only if they have expired or are set to expire within 15 minutes. Multiple actions can trigger an OAuth refresh:

• Fetching the connection via the API or SDK
• Sending a proxy request
• Executing an action or sync
• Displaying the connection credentials in the Nango UI
• Performing a manual refresh in the Nango UI
• Periodic automatic refresh by Nango

Some APIs expire refresh tokens that are not used, requiring the end user to reconnect. To prevent this, Nango ensures that OAuth credentials are refreshed at least once every 24 hours.

If a connection fails to refresh for 3 consecutive days, Nango will stop attempting automatic refreshes. However, fetching the connection via the API or UI will still attempt a refresh.

Nango implements locking mechanisms to ensure that only one refresh happens at a time, and all requests for connection credentials receive the latest valid tokens, regardless of concurrent requests.

​

Manual refresh

You can manually refresh an access token in the Nango UI:

1. Go to the Connections tab
2. Select a connection
3. Open the Authorization sub-tab
4. Click the refresh button (circular arrows) next to the Access token field

​

Handling refresh failures

Refresh failures are surfaced in the Nango UI from the first failure.

If a connection repeatedly fails to refresh, the usual resolution is to ask the end user to reauthorize the connection. Ideally, this should be done through your product using the re-authorization flow.

​

API keys & basic credentials

• API keys and basic credentials do not require refreshes.
• Nango periodically checks their validity by calling an authorized endpoint on the external API.
• If a credential check fails for 3 consecutive days, Nango will stop checking its validity.
• Any failure in API key or basic authentication validity is reported in the Nango UI.