Security
OAuth Refresh Token Cleanup: Retire Long-Lived Sessions After Apps Change
Refresh tokens can outlive the application design that created them. An integration is replaced, scopes are narrowed, mobile clients move to a new redirect URI, or a support tool stops needing offline access. The old grants may keep working because users rarely revisit consent screens and service accounts rarely announce themselves.
Cleanup should reduce long-lived access while protecting legitimate background work.
Separate active sessions from stale grants
Inventory by client id, app owner, scopes, user or service account, last refresh, token lifetime, consent source, and replacement app.
| Token clue | Evidence to inspect | Cleanup decision |
|---|---|---|
| No recent refresh | Background job cadence and user activity | Candidate if outside real use cycle |
| Broad scopes | Current feature needs and consent text | Narrow before revoking if app remains active |
| Old client id | Redirect URI migration and release history | Retire after all clients use the new app |
| Service account grant | Scheduler, connector, or data export ownership | Confirm replacement credentials first |
| Unknown owner | App registry and helpdesk tickets | Ownership gap requiring escalation |
Use your identity provider or authorization server reports to review grants before revocation. The important evidence is not merely age; it is whether a current workflow still needs offline access.
Evidence checks for refresh tokens
Look for:
- Last successful refresh time and token family rotation history.
- Scopes actually used by API calls, where logs make that visible.
- Redirect URIs, mobile bundle ids, or integration names tied to the old client.
- Customer or employee-facing apps that still show the old consent.
- Scheduled jobs that fail only when a token refresh is attempted.
Do not rush when the grant supports payroll, billing, customer data export, incident response, or production deploys. Also slow down when a token belongs to an installed desktop or mobile app; users may not be online during the review window.
Reduce access before revoking
First, move active integrations to the current client and scope set. Second, shorten lifetimes or require re-consent for risky grants. Third, notify owners of tokens with no recent refresh. Fourth, revoke stale grants in a controlled window with support ready to distinguish expected reauth from real breakage.
For customer-facing integrations, record customer communication and retry behavior before cleanup. A revocation that is technically correct can still create support load if the app cannot guide users back through consent.
Prevent long-lived token clutter
New OAuth clients should declare why refresh access is needed, which scopes are required, who owns the client, and what event triggers grant review. Scope changes and redirect URI migrations should include stale token cleanup in the release checklist.
Key takeaways
- Refresh token cleanup reduces stale long-lived access.
- Last refresh time must be interpreted against real background job cadence.
- Scope narrowing and client migration often come before revocation.
- New OAuth clients should include ownership and token review triggers.