Refresh tokens hard-expire after five years, first ones in February 2027
- Provider
- QuickBooks
- Endpoint
POST /oauth2/v1/tokens/bearer- Effective
- 2027-02-01
- Severity
- high
- Change
- auth
- Status
- verified
What changed
Intuit refresh tokens now have a maximum lifetime of five years, even if they are used regularly. For apps on restricted or granular scopes, tokens issued from February 2022 start expiring in February 2027. For com.intuit.quickbooks.accounting and com.intuit.quickbooks.payments, tokens issued from October 2023 start expiring in October 2028. Intuit gives only the month, so the effective date here is the first day of that month.
What to do
On token requests, send the header x-include-refresh-token-hard-expires-in: true (Intuit's docs also list an x_refresh_token_hard_expires_in=true parameter) and store the returned x_refresh_token_hard_expires_in (seconds left in the five-year lifetime) alongside the token. Treat invalid_grant from /oauth2/v1/tokens/bearer as a disconnect that needs the user to reconnect, not as a retryable error. Prompt users to re-authorize before the hard expiry, and set the Reconnect URL in the developer portal app settings.
Sources
- Provider notice (2025-11-12)
- https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0
- https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/faq
- https://developer.intuit.com/app/developer/qbo/docs/release-notes/general-release-notes
Check your code
npx shapi-cli scan .shapi scan lists the call sites this change affects; shapi fix repairs them test-first when the advisory has an automatic fix. All advisories · Markdown · OSV · JSON