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

Open your terminal and run:

~/.qb-distributor-mcp/venv/bin/python -m qb_distributor_mcp.auth_qb

This prints an Intuit consent URL. Paste it into your browser, sign into the QuickBooks company you want to connect, click Connect. Intuit redirects you to sidequestautomation.com/qb/callback, which is a static page that captures the authorization code and your realm ID in two copy-paste boxes. Copy each one back into the terminal at the prompts.

The terminal prints two lines that look like:

QB_REALM_ID=9341457145807883
QB_REFRESH_TOKEN=RT1-109-H0-1788525963cx52dybvpworn5gantq3

Open ~/.qb-distributor-mcp/.env in any text editor, replace the existing two lines, save. Then re-inject the env vars into Claude Desktop's config (the install prompt gives you the one-liner) and Cmd+Q + reopen Claude. Your next QuickBooks request will work.

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.