## 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

```text
Auth error: token refresh failed with invalid_grant; the refresh token is expired or revoked.
```

## Steps

1. Detect refresh failure distinctly from access-token expiry. Expected: the run knows re-auth is needed, not just refresh.
2. Alert for re-authorization: this step needs the authorization flow, which may need a human. Expected: the right person is paged.
3. Complete the authorization flow and store the new credential pair. Expected: fresh tokens.
4. Resume the run from its checkpoint. Expected: no work lost.
5. 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