Loading

Enforce One-Time-Use Refresh Tokens with Refresh Token Rotation (RTR) in Salesforce

Fecha de publicación: Oct 21, 2026
Descripción

Refresh tokens that can be reused multiple times create a security vulnerability because a single stolen token provides ongoing unauthorized access to Salesforce. 

To prevent malicious users from exploiting compromised tokens, implement Refresh Token Rotation (RTR) on your connected app or external client app OAuth configuration. This setting enforces single-use refresh tokens by issuing a new token with each exchange and immediately invalidating the previous one.

This safeguards against token theft and any attempted reuse of an invalidated refresh token results in the immediate revocation of the current refresh token and all associated access tokens, requiring the client to re-authenticate via a new flow.

Solución

This article explains how to set up and roll out Refresh Token Rotation (RTR) on your External Client App or Connected App, enforcing single-use refresh tokens to protect against token theft.

Plan Your Activation for Refresh Token Rotation

Before activating this feature, Administrators and Architects must plan and fully understand the expected outcomes. To implement a Refresh Token Policy, you must sequentially audit your current OAuth scopes and client dependencies, update your application logic to securely persist and rotate tokens, and implement an error recovery mechanism to prevent lockouts.

Step 1: Audit Your Current State

Before changing settings, verify that your current flows support rotation.

  • Check Scopes: Ensure your current OAuth requests include the refresh_token or offline_access scope. Rotation only applies to flows that issue refresh tokens.
  • Identify all OAuth Clients: Catalog every external consumer such as middleware, mobile applications, or local apps associated with that specific Connected App's Consumer Key. All client apps must be updated to support token persistence simultaneously to avoid a synchronization failure.

Step 2: Remediate Your Client Apps

Your app must be rotation-aware and should implement handling of refresh tokens in the OAuth flow.

  • Modify the Token Parser: Locate the function that handles the response from /services/oauth2/token.
  • Implement the Token Swap: Change your logic to look for a refresh_token in the response of a refresh request.
  • Update Persistence: Write logic to overwrite the old refresh token in your secure storage with the new one provided in the response.
  • Legacy Apps: If you do not have control over the application, and if the application doesn't support rotation of refresh tokens, understand and communicate the implications of enabling refresh token rotation.

Step 3: Implement Error Recovery (invalid_grant)

The following is an example of a returned error from an OAuth 2.0 refresh token flow. Handle this error and log it so you have a clean audit trail. Then, initiate a new authentication flow. The new flow invalidates all refresh tokens, effectively safeguarding against the reuse of stolen tokens. Failing to do so may result in the user being locked out.

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

This response indicates the refresh token used in the request is no longer valid, either because it was already rotated out by a prior exchange, or because it was revoked following a detected reuse attempt. Your client application should catch this specific error and initiate a fresh authentication flow rather than repeatedly retrying with the same invalid token.

 

Custom Mobile Apps Built with Salesforce Mobile SDK

If your org has custom iOS or Android apps built with Salesforce Mobile SDK, upgrade them to Mobile SDK 14.0 or later before you enable Refresh Token Rotation on the connected app or external client app they use. This applies to native, hybrid, and React Native apps.

1. Upgrade to Mobile SDK 14.0 : Update the app, then test sign-in, token refresh, and session recovery before you release it.

2. Release the updated app : Publish it to the Apple App Store and Google Play, or distribute it through your MDM or enterprise channel.

3. Confirm adoption : Turning on RTR affects every installed version of the app at once. Before you enable it, make sure most or all of your users have installed the updated version. If you use an MDM, consider making the update mandatory.

4. Enable RTR : Once your users are on the updated app, follow the steps to turn on RTR.

How to Set Up Refresh Token Rotation on an External Client App

In your org, log in as an Admin user. For a new application, go to:

Settings > External Client App Manager > New External Client App. Check Enable OAuth in API.

External Client App creation screen with Enable OAuth checkbox checked

Then, in the security section, enable Refresh Token Rotation. You will be presented with additional configuration options. In the security section, check the checkbox against "Enable Refresh Token Rotation".

Security section showing the Enable Refresh Token Rotation checkbox and additional configuration options

Salesforce recommends using External Client Apps in all situations and migrating connected apps to External Client Apps.

Número del artículo de conocimiento

005316711

 
Cargando
Salesforce Help | Article