salesforce oauth invalid_grant expired error

Fix Salesforce OAuth invalid_grant on expired refresh tokens

TL;DR

invalid_grant on a Salesforce refresh means the refresh token expired, was revoked, or the connected app changed. Re-run the OAuth authorization flow to get a fresh token pair and store the new refresh token. Patching the old one is impossible; only a fresh grant fixes it.

The error

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

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=salesforce oauth invalid_grant expired error"

Fix it

Step 1: Confirm the refresh token is dead

Attempt one refresh with the stored refresh token and read the error.

Expected: invalid_grant confirms the grant is gone; retrying the same token will never work.

Step 2: Re-run the full authorization flow

Send the user (or the integration owner) through the Salesforce OAuth authorize URL again.

Expected: You receive a fresh authorization code.

Step 3: Exchange the code for a new token pair

POST the code to the Salesforce token endpoint and store both the new access and refresh tokens.

Expected: The token endpoint returns 200 with a new refresh token.

Step 4: Update the stored credentials

Replace the old refresh token in your secrets store or integration config.

Expected: The integration now holds only the fresh token pair.

Step 5: Verify the integration resumes

Trigger a sync or API call through the integration.

Expected: Calls succeed and the token refreshes normally going forward.

When this applies

• Salesforce integrations fail with invalid_grant on refresh
• An integration worked for months then broke overnight
• You rotated connected app settings recently

When it doesn't

• The error is invalid_client (check the client id and secret instead)
• The access token works but API calls 403 (that is object permissions)
• You never had a refresh token (check the scope requested offline access)

Compatibility

Salesforce OAuth 2.0 web server flow. Connected app settings as of 2026.

Variant phrasings

salesforce refresh token expired invalid_grant

Salesforce refresh tokens can expire on inactivity or policy. The fix is always a fresh authorization.

salesforce oauth token revoked

Revocation by an admin or by the user looks identical to expiry. Same fix: re-authorize.

invalid_grant after connected app change

Changing connected app policies can invalidate outstanding grants. Re-authorize every integration after such changes.

Why it happens

Refresh tokens are long-lived grants, not permanent ones. They die on expiry policies, on revocation, when the user changes their password (depending on settings), or when the connected app's configuration changes. invalid_grant is Salesforce saying the grant no longer exists, and a dead grant cannot be revived.

Edge cases

• Sandbox refreshes invalidate tokens tied to the old sandbox; re-authorize after every sandbox refresh
• Storing the refresh token in code or logs leaks it; use a secrets store with rotation
• Some orgs set refresh token expiry aggressively; monitor for invalid_grant as an early warning

If it still fails

• Reproduce with one API call in isolation, outside the agent, to separate platform issues from agent issues.
• Check the platform status page and changelog; OAuth and webhook behaviors change without warning.
• Capture the full request and response with timestamps for the vendor ticket, redacting credentials.
• Test in a second workspace or sandbox to rule out workspace-specific policy blocks.
• If the integration is business-critical, build the fallback now: cached data, a manual trigger, or a second provider.

Prevention

• Store OAuth credentials in a secrets manager with rotation reminders.
• Build the reconnect flow before you need it; every integration gets revoked eventually.
• Log token ages so expiring grants are visible ahead of time.
• Keep a sandbox integration for testing config changes.
• Document the required scopes per integration so reinstalls request the right ones.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7UWvZSZVyxWrPXf60xBTCA