OAuth scopes removed without notice broke all token refreshes in production

[cervinakuy]

Confirmation

• I confirm this post does NOT contain sensitive data for my account.

Question / discussion

What Happened

Today (2026-08-12) at approximately 14:54 UTC, our OAuth token refreshes began failing. The cause was that eight scopes we had previously been granted are no longer returned:

1. billing_r 2) cart_r 3) cart_w 4) favorites_r 5) favorites_w 6) feedback_r 7) recommend_r 8) recommend_w

Root Cause

These appear to have been removed from the API entirely. components.securitySchemes.oauth2 in the official API (and the generated spec) now defines only 12 scopes, and searching the full document returns zero occurrences of any of the eight.

The change took effect mid-flight: our scheduled refresh at 14:09 UTC succeeded and the next one at 14:54 UTC failed, with no deploy on our side in between.

Because our client still requested the previous 20-scope set, the narrower scope in the refresh response triggered a blocking scope-change error. That meant every refresh failed, including the scheduled job whose only responsibility is renewing the token; so once the access token expired all our backend workers lost all Etsy API access for roughly two hours.

The Impact: Customer orders went unprocessed during that 2 hour window.

Our Fix

We use oauthlib in Python, and our immediate short-term fix was setting OAUTHLIB_RELAX_TOKEN_SCOPE (this is not set by default). We've since trimmed our requested scopes to the 12 currently defined, which is also another fix option.

Our Requests (on behalf of the Etsy Developer Community)

We kindly have two requests:

1. Please announce OAuth scope removals in advance. A short note on here beforehand would have let us adjust our requested scopes ahead of the change rather than diagnosing it mid-outage. Scope removals are unusual among breaking changes in that they can break authentication itself, so even working integrations that never call the affected endpoints go down.

2. The authentication guide at https://developer.etsy.com/documentation/essentials/authentication still lists all 20 scopes, including the eight removed. It contradicts the API spec / generated spec, which made this much harder to identify. We initially ruled out a scope change because of that page.

Happy to provide more detail if it's useful.

Kind regards,
Cervinakuy

[openapi-support[bot]]

Thank you for reporting this issue.

The refresh failures for integrations still requesting the older scope set were not intended, and that issue has>

Thank you for your continued support and use of our API.