salesforce refresh token expired mid-run for the dedup agent: auth error
Handles an expired Salesforce refresh token mid-run: detect it, re-authorize, and resume. Use when refresh itself fails during a long run. Not for access-token expiry.
TL;DR
The refresh token itself expired or was revoked, so the usual refresh recovery fails. Detect the refresh failure distinctly, trigger a full re-authorization (this one needs human or stored authorization), then resume from the checkpoint. Refresh-token expiry is rare but terminal without a re-auth path.
Error
Auth error: token refresh failed with invalid_grant; the refresh token is expired or revoked.Steps
- Detect refresh failure distinctly from access-token expiry. Expected: the run knows re-auth is needed, not just refresh.
- Alert for re-authorization: this step needs the authorization flow, which may need a human. Expected: the right person is paged.
- Complete the authorization flow and store the new credential pair. Expected: fresh tokens.
- Resume the run from its checkpoint. Expected: no work lost.
- Investigate why the refresh token died: rotation policy, revocation, or inactivity timeout. Expected: the cause addressed so it does not recur.
When to use
- Refresh attempts fail with invalid_grant.
- Long-lived agents suddenly cannot authenticate.
- After admin revocations or policy changes.
When not to use
- Access-token expiry (normal refresh handles it).
- Invalid client configuration (fix the connected app).
Tool compatibility
- Salesforce OAuth refresh and authorization flows.
- Agent credential storage and alerting.
Variant phrasings
refresh token expired
Re-authorize; resume from checkpoint.
invalid_grant on refresh
Same recovery path.
Why it happens
Refresh tokens expire on rotation policies, revocation, long inactivity, or org changes. They are designed to be long-lived but not immortal.
Edge cases
- Some flows do not issue refresh tokens at all; know which flow you use.
- Storing refresh credentials needs proper secret management; never in code.
- Test the re-auth path before you need it; an untested path fails when it matters.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_7bTV8ZhaXavcrlX1UEIBkw