Why Are Refresh Tokens Expiring? – Salesforce Connected App

Question

We have configured our web application to authenticate with Salesforce using OAuth2 via a Connected App. The Connected App is set up to ensure that refresh tokens never expire unless manually revoked. When an admin connects the Connected App to our web application, we securely store the received refresh token so that we can make API requests on behalf of that user later. The OAuth scope includes "offline_access" and "refresh_token" for the admin login page.

However, while the application functions correctly throughout the day, we occasionally encounter the following error when attempting to obtain a new access token using the stored refresh token:

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

Despite verifying our settings, which indicate that refresh tokens should not expire, we are trying to understand why this issue occurs. Are there scenarios where a refresh token can expire, even when set to never expire? Does frequent use of the refresh token contribute to its expiration? Is it necessary to periodically refresh the refresh token itself?

Once this issue occurs, the only way we have found to recover is by requiring the user to reauthorize the app, which disrupts all API communication. What is the correct recovery process in this situation? Is there a way to prevent users from having to manually reauthorize?

We also have non-admin users who authenticate via OAuth through the same Connected App. Should we avoid requesting "offline_access" and "refresh_token" for users who only need authentication and not long-term API access? We have tried different scope configurations, but they don’t seem to affect this issue.

We’ve also seen suggestions that Salesforce limits the number of active refresh tokens per user, with a maximum of five before older ones expire. However, we have tried signing in multiple times as both admins and users without consistently reproducing the issue. Is there a definitive limit on refresh tokens per user? Could IP address restrictions or other security settings contribute to token expiration?

Additionally, we have noticed a “Use Count” field in the OAuth settings, but its exact function is unclear. What does this count represent? Does it increment with every OAuth token exchange, or only under certain conditions such as when "offline_access" or "refresh_token" is used? Is there a limit on this count, and does it affect token validity?

Answer

The issue of refresh token expiration despite being set to “never expire” is often related to the Salesforce Connected App token limits. Each user can only have five active access tokens per Connected App. Since refresh tokens are capable of generating new access tokens, they are included in this count.

If a user logs in and receives a sixth token, the oldest token is invalidated, meaning any API calls attempting to use that invalid refresh token will fail with the "invalid_grant" error.

Here’s an explanation from the Salesforce documentation:

“A given user may only have five access tokens authorized for a given connected app. Since each refresh token can potentially issue an access token, they are counted in that total. The way to think about this is that only the most recent five authorizations are valid. When the user logs in a sixth time, the oldest authorization is invalidated, and that refresh token will no longer work.”

How to prevent refresh token expiration?

1. Avoid requesting refresh tokens unnecessarily. If a user only needs authentication, do not include "offline_access" or "refresh_token" in the scope.
2. Use separate Connected Apps for different purposes. If some users only need authentication while others require long-term API access, create separate Connected Apps for each use case.
3. Consider using the JWT Bearer Token flow. Instead of storing refresh tokens, you can use the JWT flow, which allows for predictable authentication without relying on refresh tokens. This eliminates the risk of unexpected token expiration.

How to recover when a refresh token expires?

If a refresh token has been invalidated, the only way to recover is for the user to reauthorize the application. However, to minimize disruptions, consider implementing a graceful fallback mechanism in your app:

• Detect the "invalid_grant" error.
• Prompt the user to re-login before making additional API requests.
• Log and alert administrators when refresh token expiration occurs frequently.

Understanding “Use Count” in OAuth settings

The “Use Count” represents the number of times an application has been granted access by a user.

• Every time a refresh token is issued, this count increases.
• If a user logs in multiple times and obtains multiple refresh tokens, each token request increments this count.
• It does not directly limit token validity but helps track refresh token usage.

Final Recommendations

• If long-term API access is needed, reduce unnecessary logins. Refresh tokens should only be used when necessary.
• If users frequently log in, expect old refresh tokens to expire. Avoid re-authenticating users unnecessarily, as it can lead to token exhaustion.
• Consider switching to the JWT Bearer Token Flow. This eliminates the need for refresh tokens while maintaining predictable access.

By following these best practices, you can reduce the likelihood of encountering "invalid_grant" errors due to expired refresh tokens while ensuring seamless authentication and API access for your users.

Job-Oriented Salesforce Training with 100% Money Back Guarantee

Our Salesforce course is designed to provide a comprehensive understanding of the Salesforce platform, equipping you with essential skills to excel in the CRM industry. The curriculum covers key modules like Salesforce Admin, Developer, and AI, combining theoretical concepts with hands-on learning. Through real-world projects and interactive exercises, you’ll gain expertise in solving complex business challenges using Salesforce solutions. Our experienced instructors ensure you develop both technical proficiency and industry insights to succeed in the Salesforce ecosystem.

Beyond technical skills, our Salesforce training in Mumbai offers personalized mentorship, certification guidance, and interview preparation to enhance your career prospects. You’ll have access to extensive study materials, real-world project experience, and continuous support throughout your learning journey. By the end of the course, you’ll be well-prepared for certification exams and possess the problem-solving skills that employers value. Take the first step in your Salesforce career—enroll in a Free Demo today!