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 with force_refresh=true 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.

​

Refresh and validity in scripts

Inside your scripts, Nango is caching locally the credentials for a small amount of time to reduce latency. After that period, if needed, we will query our API again to get updated credentials.

If you have retry enabled in your proxy calls:

• If the credentials expires during a proxy call, we will refresh the credentials and retry automatically.
• If the credentials are invalidated (e.g. the user revoked access) during an HTTP call, we will retry one more time.

If you don’t have retry enabled in your proxy calls:

• No automatic retry will be done, and your script will fail.

​

Storing credentials in a variable

It’s not recommended to store the credentials in a variable, because they won’t be automatically refreshed.

// ❌ Don't
const connection = await nango.getConnection();
while (true) {
    doSomethingWith(connection.credentials);
}

// ✅ Do
while (true) {
    const connection = await nango.getConnection();
    doSomethingWith(connection.credentials);
}