GitHub App OAuth BAD_REFRESH_TOKEN — What it means & how to fix it

When using GitHub App OAuth flow, a "bad_refresh_token" error can occur due to an incorrect or expired refresh token, halting various processes until the issue is resolved. This error often surfaces in mature OAuth flows as "invalid_grant" and requires re-authentication or fixing token lifecycle issues. Common causes include failure to store the new refresh token after a successful update, expiration of the token after approximately six months, revocation of the app's authorization by a user or organization, race conditions where multiple workers attempt to refresh simultaneously, and security revocations due to suspicious activity. To address these issues, it's essential to persist the latest refresh token, eliminate refresh races by allowing only one refresh per connection at a time, and quickly detect revocation, prompting users to re-authenticate when necessary. Adopting engineering practices like storing rotated tokens, refreshing regularly to avoid expiration, preventing race conditions, monitoring error spikes, and creating a user-friendly reconnect flow can prevent refresh token problems. Nango offers a solution by providing an open-source auth layer that manages OAuth token lifecycle issues, ensuring secure storage, automatic refreshes, and concurrency-safe logic, allowing developers to focus on their products instead of token management.