Why Adding a New OAuth Scope Breaks Everything

If you add a new OAuth scope to an existing integration, every customer who already connected it needs to reauthenticate, no exceptions. This isn't a quirk of any particular platform or a policy decision that varies by provider. It's a structural consequence of how OAuth authorization works, baked into the spec itself. The token your user received when they first connected your integration is a frozen record of exactly what they approved at that moment. It cannot be retroactively expanded to cover permissions they never consented to. Understanding why this is true, and what it means operationally, is what separates teams that handle scope changes smoothly from teams that get caught flat-footed when their entire installed base suddenly can't access a feature.

Why Token Scopes Are Frozen at Issuance

When a user clicks "Allow" on a consent screen, they're doing something more significant than most people realize. They're delegating authority — saying: "This application can act on my behalf, but only in these specific ways." The authorization server takes that agreement and issues an access token that encodes exactly what was approved, right then, right there. The scopes aren't a label attached afterward. They're part of the token's DNA.

RFC 6749, the base OAuth 2.0 specification, treats this exchange as a one-time transaction. The client requests scopes. The server confirms what it actually granted. There's no mechanism in the spec to go back and expand a token's scope after the fact. Refresh tokens follow the same rule. You can't use one to upgrade what an access token is allowed to do. If you want broader permissions, you need a new authorization grant, which means a new consent event. A token is a signed record of a past consent moment. Its scope ceiling was set the second it was issued.

What Happens When You Add a New Scope

When you add a new scope to your app configuration, maybe a new API feature, an expanded workflow, or an additional data source, the change looks small on your side. On the user's side, nothing has happened yet. That's exactly the problem.

Every access token already held by authenticated users was issued before that change. Those tokens encode only the old scope set. Microsoft's documentation on Azure AD and Entra ID makes this explicit: the service principal representing the app within a customer's tenant does not automatically inherit newly added permissions. The old token keeps working for what it was issued to do. It simply cannot do anything the new scope would cover. That gap is structural, and no server-side patch closes it.

Slack says the same thing in its developer documentation: existing installations don't automatically gain new permissions when scopes are added. Users have to reinstall or reauthorize. Shopify's behavior mirrors this — merchants get redirected through OAuth when the app's requested scopes no longer match what was granted at install time. One asymmetry worth flagging: scope reductions are silent. Shopify, for instance, simply removes access when the app opens, with no prompt to the merchant. Scope additions, though, always require affirmative consent. The user has to say yes, and there's no way around that.

Errors When an Under-Scoped Token Hits the API

The failure mode is blunt. There's no graceful degradation when a token missing a required scope tries to call an endpoint that needs it — the call simply fails. The standard response is an insufficient scope error. The token is valid and authenticates the caller just fine, but it isn't authorized for the specific operation. Google Cloud's documentation describes this as returning HTTP 400 or 401 errors depending on the specifics. The feature that requires the new scope is entirely unavailable until the token is replaced.

• The error is a signal, not a crash: it's expected and recoverable.

• The correct response is to surface the reauthorization flow, not to retry the call.

• The application UI should be built to detect this state and guide the user back through authorization clearly, rather than burying a cryptic error in a log somewhere.

How you handle the failure matters as much as the failure itself. A well-designed reauthorization experience makes users feel like the product is working as intended. A poorly designed one makes them feel like something is broken.

Why Reauthentication Is Unavoidable, Not Conventional

It would be technically possible to build a system that silently grants an application new permissions when a developer updates their scope list. The reason no reputable OAuth implementation does this is that it would fundamentally destroy the trust model that makes delegated authorization work. The user's "Allow" at the consent screen is supposed to be a durable, auditable record of what they agreed to delegate. Silent scope expansion means the application acquires authority the user never approved — a significant violation of the user's agency, not merely a technicality.

The OAuth spec preserves that agency deliberately. Even when you add a completely legitimate, obviously benign new scope, each individual user retains the right to refuse it. The reauthorization flow is the mechanism that enforces that right.

Google's scope verification process adds a further layer on top of this: adding sensitive or restricted scopes requires app re-verification before those scopes can be exercised at all. The consent requirement operates at both the platform level and the individual user level simultaneously.

RFC 9700, the IETF's current best practice document for OAuth 2.0 security published in January 2025, reinforces scope minimization explicitly. Wider scope means wider exposure if a token is stolen or an integration is breached. The blast radius of any compromise is defined by the scopes the user approved — nothing more, nothing less. When Drift was compromised, attackers inherited the scopes that customers had already approved for that integration, across a large number of affected organizations. The granted scopes defined exactly how far the breach reached into customer data, with no additional authentication step required. The security boundary was the consent boundary.

Incremental Authorization Reduces Scope Debt

The best solution to scope-related reauthentication friction is to not accumulate scope debt in the first place. The industry pattern for this is called incremental authorization (sometimes called progressive authorization), requesting only the permissions you need for what the user is doing right now, rather than every scope the app might ever need. You request scopes tied to specific actions, not a defensive "just in case" list.

The IETF's draft on OAuth 2.0 Incremental Authorization formalizes this approach. Request basic profile scopes at sign-in. Request storage or calendar scopes only when the user actually tries to do something that requires them. The permission request arrives with obvious, visible justification. The user understands why they're being asked, consent rates go up, and confusion goes down. Google's OAuth 2.0 best practices explicitly recommend this pattern and note something worth building your design around: when requesting multiple scopes, be prepared for users to deny some of them. Graceful degradation per scope is the correct posture, rather than an all-or-nothing gate.

Shopify has taken this further with a formal optional scopes API. Apps can query which scopes are currently granted, request additional optional scopes at runtime through a permission-grant modal, and revoke scopes that are no longer needed. Scope management becomes a runtime capability rather than a decision locked in at deploy time. The IETF draft also specifies an include_granted_scopes parameter that lets a new authorization request absorb the user's full previous grant, so the client doesn't have to independently track accumulated scope history across sessions.

The Operational Cost of Scope Changes at Scale

A single scope addition doesn't just affect new users — it triggers a reauthentication requirement for every customer who has already connected the integration, the entire installed base, all at once. In multi-user SaaS environments, this compounds further. The person who originally authenticated the integration is often not the person using it day-to-day. It might have been a technical co-founder during initial setup, a contractor who's no longer around, or an IT admin who handles dozens of these connections. That person may not even know a reauth is needed, while the person hitting the error in production definitely didn't expect it.

Shopify's documentation surfaces this directly: if the person accessing the app doesn't have the store-owner-level permissions needed to complete OAuth, the app becomes inaccessible to them until someone with the right permissions shows up and reauthorizes it. Slack's reinstallation requirement is workspace-level. Any member can technically accept new scopes through an installation link, but coordinating that across a large customer base requires real communication, deliberate outreach, and in-app guidance. It doesn't happen on its own.

Scope changes that happen frequently make all of this worse. Customers encountering repeated reauthorization prompts start to see the integration as unstable. Even if each individual reauth is completely legitimate, the cumulative experience erodes trust. Teams that recover fastest from scope changes treat reauthorization as a first-class user journey before it ever becomes necessary. That means surfacing what failed, explaining what new permission is needed and why, and making the path back to authorized state obvious. At scale, scope management is an operational discipline, and the decision of when to add a scope and how to communicate it has measurable impact on integration availability and customer trust.

Principles for Teams Building Integrations

Scope design is an upfront architectural decision. The scopes you request at launch define your reauthentication surface for the life of the integration. Treat that list seriously from day one.

Least-privilege applies here exactly as it does everywhere else. Request only what you need, document why each scope is necessary, and revisit the list deliberately when your product expands, not reactively when something breaks.

Reauthorization is a user journey, not an error state. Surface what failed, what's being requested, and why. Make the path back to authorized state obvious, not buried in settings, not a cryptic HTTP 401 error passed through to the user as-is.

Avoid scope explosion. Adding scopes casually, frequently, or defensively multiplies the reauthentication burden across your entire user base. It also creates a scope inventory that becomes genuinely difficult to audit over time. Per Curity's analysis, that audit complexity is a real operational liability.

The multi-integration surface compounds. If your product connects to many third-party services, each connector has its own scope model, its own provider-specific reauthorization behavior, and its own set of customer authorization states to track. The operational surface grows with every integration you add. Platforms that provide managed connectors handle the per-provider OAuth mechanics, scope tracking, and reauthorization flows out of the box. The scope-change problem doesn't disappear, but the infrastructure for detecting and surfacing it is already built.

The principle that ties all of this together is the same one at the start: a scope is a user's grant, encoded at a specific moment in time. Every decision about when to request scopes, how to request them, and how to handle the gaps that emerge should reflect one simple truth: the user is always the authority on what gets delegated.