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

Integrating with Xero's accounting API using OAuth 2.0 often leads to refresh token failures, commonly resulting in an "invalid_grant" error that disrupts invoice syncing and transaction imports. This issue arises when the refresh token is invalid, expired, revoked, or when using a stale token after rotation, and requires addressing the token lifecycle rather than treating it as a transient network problem. The guide provides strategies to diagnose and resolve these errors, such as ensuring the latest refresh token is used, verifying refresh requests, managing refresh concurrency, and re-authorizing when necessary. Additionally, preventative measures include proactively refreshing tokens before they expire, treating token updates as mandatory, and implementing a clear reconnection flow for users. Tools like Nango can automate aspects of OAuth token management, handling refresh token rotations and revocations, thereby allowing developers to focus on product features instead of token lifecycle complexities.