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

GitHub App refresh tokens can fail with a "bad_refresh_token" error when the token is incorrect or expired, leading to halted background syncs and user actions until the issue is resolved. This error occurs when a backend POST request to GitHub to swap a refresh token for a new access token fails, often due to the token being expired, revoked, or not properly updated after a successful refresh. Common causes include failing to store a new refresh token after it is issued, token expiration, user or organization revocation of app authorization, and race conditions where multiple workers attempt to refresh the same token simultaneously. To address these issues, developers should ensure they are using the latest refresh token, eliminate refresh race conditions, and quickly detect token revocation to prompt re-authorization. Employing engineering practices such as storing rotated tokens, refreshing tokens on a set cadence, and monitoring error spikes can help prevent these problems. Nango, an open-source auth layer, offers a solution by managing OAuth token lifecycle concerns, providing secure storage and automatic token refreshes to alleviate the burden on developers building GitHub App integrations.