Salesforce OAuth refresh token invalid_grant — What it means & how to fix it

If you work with the Salesforce APIs you are bound to encounter this OAuth error:

“error”: “invalid_grant”

In this post we will help you understand why this happens, and how you can fix it.

Spot the error

A refresh token error from Salesforce looks like this:

{
  "error": "invalid_grant",
  "error_description": "expired access/refresh token"
}
  

This response is returned from the https://login.salesforce.com/services/oauth2/token endpoint.

Depending on the root cause, the error code and the error description can be slightly different:

invalid_grant

invalid_grant

invalid_client

unsupported_grant_type

Unfortunately, all of these errors are permanent. The only way to fix them is to ask the user to re-authenticate your integration with Salesforce.

Why was the refresh token revoked?

Tl;DR: There is no way to know for sure why a specific OAuth access token, or refresh token, has been revoked by Salesforce.

But there are some common causes you should be aware off:

Access token limit per user reached

Each “External Client App” (previously called “Connected App”) can have a maximum of 5 concurrent access tokens (and refresh tokens) for each user.

If you ask the user to re-auth, and 5 access tokens have already been issued, Salesforce will revoke the oldest of the 5 access/refresh token pairs.

If you are asking your users to re-auth a lot, this could be the root cause.

“Immediately expire refresh token” policy

Salesforce lets authors of External Client Apps define a detailed policy for how long refresh tokens should be alive:

The screenshot above shows the default values as of July 2025. You can find these settings in your External Client App details → Policies tab → OAuth Policies.

If the token policy is set to “Immediately expire refresh token”, Salesforce will immediately revoked the access token on issue. In effect, this disables the refresh token mechanism.

Crucially, this setting is also available to your users:

Admins of Salesforce organisations, where your External Client App is installed, can override your app’s default refresh token policy.

If they do this you may see every token refresh for users of this org fail. In our experience this is rare, but it’s possible.

User/admin revoked the Connected App

The user, or an admin of their Salesforce org, may have revoked access of your External Client App.

Salesforce will not proactively inform you of this, but all API requests will error and token refreshes will fail.

The only fix here is to ask your user to re-authenticate.

User password reset / user deactivated

Salesforce revokes all access and refresh tokens of the user when the user changes their password. There is no option to disable this feature.

If this is the case, you will see an authentication failure message from Salesforce on the token refresh. The same error message is also shown if the user has been deactivated in the Salesforce organization.

Ask the user to re-authenticate (if they have not been deactivated).

Refresh‑token rotation (new in Spring 24)

Note: If you use Nango to for your Salesforce OAuth flow this will never apply. Nango automatically handles this correct for you.

With the Spring 2024 release Salesforce introduced an option to issue a new refresh_token with every token refresh flow.

You will need to store this new refresh token as the old refresh token automatically gets revoked.

This setting is off by default, but can be enabled by you or the admin of a Salesforce org where your External Client App gets installed.

How to fix the refresh token error

1. Check if a policy error may be at fault

If you think the refresh may have failed due to a policy configuration (see section above), contact the admin of the Salesforce organizatin where your app was installed. Only they can change override settings for their org.

Once this is fixed, proceed with step two here.

2. Ask the user to re-auth

The only way to get a new, valid access and refresh token pair is to ask the user to re-authenticate your application.

Show a prompt in your app about the expired access, and ask the user to go through the OAuth flow again.

How to prevent refresh token issues

Refresh token failures can always happen. But a few best practices can go a long way to minimize them:

• Check you OAuth refresh token policiesMake sure the setting is not set to “Immediately expire refresh token”. Preferably, configure a long lifetime for your refresh token.
• Refresh tokens on a scheduleWith most policy settings refresh tokens expire after a while. Set up a cron job to refresh all tokens, e.g. daily, to make sure no refresh token expires.
• Discard stale access tokens‍Once you refresh, throw the old Salesforce access token away. Some APIs run anomaly detectors and see old access tokens as a potential sign of a security breach.‍
• Always store the refresh token Salesforce send backThe new setting means it may have changed.‍
• Monitor invalid_grant spikes‍Retry once. If it fails again, mark the account for re-authentication and let the user know. If a large number of access tokens fail to refresh, especially within a single company/Salesforce org, you need to take a closer look.

Skip the headache, let Nango refresh for you

Nango’s open-source auth layer includes:

• 400+ ready-to-use OAuth integrations, including full support for all Salesforce APIs
• Seamless access token refreshing and support for rotated refresh tokens
• Real-time webhooks when a refresh token is revoked, so you can instantly prompt your user
• Observability across all token refreshes & failures

Let Nango manage the entire Salesforce OAuth token lifecycle and focus on building product features.