Salesforce refresh token expired: policies and fixes

What breaks

The integration's next attempt to get a session fails with:

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

The policy is only checked when the refresh token is used, so nothing fails until the integration next tries to renew its session. A nightly job usually fails at 2am with nobody watching.

The policies

Setup, Connected Apps, Manage Connected Apps, Edit, OAuth Policies, Refresh Token Policy:

External Client Apps express the same choices as refreshTokenPolicyType (Infinite, SpecificInactivity, SpecificLifetime, Zero) with refreshTokenValidityPeriod and refreshTokenValidityUnit (Days or Hours, among others).

If your org turned on “Limit Idle Refresh Token Time-to-Live (TTL) to 30 Days”, a policy of “valid until revoked” behaves as 30 days of inactivity, but the metadata is not updated for you. Set it to specific_inactivity:30:DAYS yourself so source control matches what the org does.

See who holds tokens

1. Setup, Connected Apps OAuth Usage. The user count opens a list with first connected, last used and use count.
2. Through the API, query OauthToken (needs Customize Application to see every user's tokens):

SELECT AppName, UserId, LastUsedDate, UseCount
FROM OauthToken
ORDER BY LastUsedDate

A query returns at most 2,500 rows, so page through larger orgs with OFFSET.

Fix it

1. Re-authorise the integration user to get a new refresh token.
2. If the expiry was not intended, change the policy. For unattended integrations, prefer “expire if not used for n” over “expire after n”, which kills a token on a fixed date even when it is used daily.
3. Revoke tokens you no longer trust from the OAuth Usage page.

Changes since 2025

• From September 2025, connected apps that are not installed in the org are blocked for new users, who see error=invalid_client with “app must be installed into org”. On Connected Apps OAuth Usage, click Install for trusted apps and Block for the rest.
• From Spring '26, new connected apps cannot be created without Salesforce Support. Existing ones keep working; new integrations use External Client Apps.

Common mistakes

1. Using “expire after n” for an unattended integration.
2. Requesting a new refresh token on every run. Each app allows five approvals per user, and the sixth silently revokes the oldest.
3. Turning on the 30-day idle limit without updating the policy metadata.
4. Ignoring the Install buttons on OAuth Usage, which leaves new users of those apps blocked.