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

Encountering the OAuth error "invalid_grant" is a common issue for those working with Salesforce APIs, often due to stale, revoked, or over-quota refresh tokens. This error, which can have various root causes such as expired tokens, incorrect client credentials, unsupported grant types, or changes in user status, requires users to re-authenticate to resolve. The potential reasons for token revocation include reaching the access token limit per user, immediate expiration policies, user or admin revocation of app access, or user password resets. To mitigate these issues, developers can follow best practices such as setting appropriate OAuth refresh token policies, scheduling regular token refreshes, discarding stale tokens, and monitoring for invalid_grant spikes. The introduction of refresh-token rotation in Salesforce's Spring 2024 release necessitates storing new refresh tokens as the old ones get revoked. Tools like Nango can automate the Salesforce OAuth token lifecycle, offering seamless access token refreshing, support for rotated refresh tokens, and real-time webhooks for token revocation alerts.