QuickBooks refresh token expired: what to do (and what we tell our customers)

Refresh tokens for QuickBooks Online die after 100 days of disuse, or whenever someone disconnects the app from inside QB Settings. The fix takes about ninety seconds. The hard part is knowing which ninety seconds.

If you got here from a 3200 error or a "Login required" message, here is what's true: your access token expired (those die after an hour), your client tried to refresh it using the saved refresh token, and the refresh failed too. There are three reasons that happens.

1. The refresh token itself expired. Intuit gives you 100 days from issue. If no request has minted a new access token in that window, the refresh token is dead and you need to redo OAuth.
2. Someone disconnected the app inside QuickBooks. Settings → Apps → Connected Apps → Disconnect. This revokes the refresh token immediately, no notice.
3. The Intuit app moved environments. Sandbox refresh tokens don't work against production and vice versa. If you flipped your QB_ENVIRONMENT in .env without re-running OAuth, you'll see a 3200.

All three have the same fix: re-run the OAuth consent flow once, capture the fresh QB_REFRESH_TOKEN and QB_REALM_ID, paste them back into ~/.qb-distributor-mcp/.env, restart Claude Desktop. Your access tokens will start refreshing again on a normal cadence.

The flow, step by step

On v0.15.15+, one command does the whole dance:

sidequest reauth-qb

It opens an Intuit consent URL in your browser, you sign into the QuickBooks company you want to connect and click Connect. Intuit redirects to sidequestautomation.com/qb/callback, the connector picks up the authorization code, exchanges it for a fresh refresh token locally using your Client Secret (which never leaves your machine), writes QB_REALM_ID and QB_REFRESH_TOKEN to ~/.qb-distributor-mcp/.env, and auto-pushes the new values into Claude Desktop's config. Tokens never print to the terminal — they're redacted as RT…XXXX in any output. Cmd+Q Claude Desktop, reopen, your next QuickBooks request works.

You no longer have to hand-edit .env for this — the command writes it for you. The only manual step is the browser sign-in to confirm consent.

Why we don't auto-recover

A few customers have asked why SideQuest doesn't just pop the browser and re-OAuth on its own. The answer is consent. Intuit requires a real human to click Connect on a real Intuit-hosted page. If we silently rewrote your refresh token, we'd be hiding a security event from you. The 90-second manual flow is the right cost.

What we do is fail loudly and helpfully. SideQuest's error responses include a one-liner pointing at the diagnose prompt — paste that into Claude Desktop and Claude walks you through this whole flow. If your token is dying mid-batch, you'll see the right answer before you see the right Intuit dashboard tab.

Keeping it from happening again

The 100-day clock resets every time the refresh token mints a new access token. If you process at least one PO every two or three months, the clock never runs out. If you go quiet for a quarter, set a reminder. Better: process a tiny test PO once a month — SideQuest's free tier (20 POs / month) covers it with room to spare.

Also: don't let anyone disconnect the app in QuickBooks unless you mean to. The Disconnect button is one click and there's no undo.