Linear OAuth refresh token invalid_grant — What it means & how to fix it

Building integrations with Linear's API using OAuth 2.0 often encounters refresh token failures, which manifest as invalid_grant errors and disrupt various workflows. These errors arise when a refresh token becomes invalid, expired, or revoked, often due to token rotation or concurrent refresh requests without proper locking mechanisms. To address these issues, it is crucial to ensure the latest refresh token is used, verify the correctness of the refresh request, and handle user revocations or app uninstallations gracefully. Implementing proactive measures such as refreshing tokens before expiration, maintaining a single-flight refresh process, and monitoring for invalid_grant trends can help prevent disruptions. Additionally, leveraging tools like Nango, which provides built-in OAuth token management, can alleviate the complexities of handling token lifecycle challenges, allowing developers to focus more on product features.