This has happened a couple times now and it is getting rather frustrating. We start receiving reports that payments are failing. After a bit of research, we find that the OAuth tokens for our third party accounts have expired (get an invalid token message when trying to refresh).
To fix this, we’ve had our third party customers click on the OAuth link again to grant our account permissions.
Why are our refresh tokens becoming invalid? We refresh the tokens once a week so I know it’s not because they have expired.
Hi there,
Since you’re refreshing weekly, you should be well within the proper refresh window for our code flow. But here’s what could still cause the “invalid token” error:
-
Your refresh job may have silently failed. If it skipped a few cycles (e.g., due to an outage or unhandled error), the access token could expire. After that, you have a 15-day grace period to refresh, but if that window passes too, the refresh token becomes permanently invalid and re-authorization is the only fix.
-
The merchant revoked access (via Square Dashboard → App Integrations). Even if they don’t recall doing it, another account admin may have.
Recommendations:
-
Verify your refresh job is actually succeeding each week (check logs for errors, not just that it ran). If it appears the refresh job is succeeding without error, can you walk me through the steps you take during this refresh job?
-
Subscribe to theoauth.authorization.revoked webhook. This fires in real-time when tokens are revoked and includes who revoked it (MERCHANT,APPLICATION, or in very rare casesSQUARE)
Relevant docs:
Let us know if any of the above matches what you’re seeing and we can dig further!