Cloudflare's Task-Based OAuth Consent: Moving Beyond All-or-Nothing Permissions

OAuth consent screens have long been an all-or-nothing affair: users either approve the full set of requested permissions or reject the entire integration. Cloudflare is changing that with a new feature called OAuth scope customization, announced on August 20, 2026. It lets users uncheck specific optional scopes during authorization, so they can drop higher-risk permissions on the spot without abandoning the whole connection.

This is especially relevant for developers building AI agents and MCP (Model Context Protocol) servers, where a single integration often requests a broad set of permissions because the agent might theoretically use them all—even if most users only need a subset. Cloudflare’s update gives users the ability to grant a narrower scope, and it puts the responsibility on developers to handle that gracefully.

The Problem: All-or-Nothing Consent

Cloudflare’s OAuth implementation already allowed clients to request a subset of their configured scopes. But once a client decided which scopes to request, users had no way to narrow them further at the consent screen. The experience was binary: accept the full request or reject it entirely.

This created friction, especially for apps that legitimately need a wide range of permissions for some features but not for everyday use. Users who were uncomfortable granting, say, write access to their zone settings had no middle ground—they either handed over the keys or walked away.

The new design leverages a flexibility that already exists in the OAuth protocol: an authorization server can issue a token with a narrower scope set than what was requested. Cloudflare builds on this by letting client owners mark specific scopes as required or optional when configuring their OAuth client. During authorization, users can uncheck optional scopes. If no optional scopes are requested in a given flow, the consent screen looks exactly as before. By default, the full requested scope set is still granted.

How It Works: Scopes Are Evaluated Per Request

One key detail: required and optional are evaluated against the scopes actually requested in a single authorization flow, not against the full set of scopes the client has configured. Cloudflare gives an example: a client has four scopes configured, two of which are marked optional. If a flow requests all four, the user can uncheck the two optional ones. If another flow only requests two of the scopes, the other two never appear and are not enforced.

This design keeps the consent screen focused on the task at hand rather than on every possible capability the app might use. It also means existing clients that don’t use optional scopes see no change in behavior.

Practical Implications for Developers

If a user unchecks any optional scopes, the resulting access token will only contain the scopes the user actually approved. Developers must check the actual granted scope set after exchanging the authorization code—they cannot assume all requested scopes were approved.

Apps that handle narrower grants gracefully—for example, an agent that operates only within the subset of permissions it received—will make users more willing to authorize. Requesting only the permissions you truly need and marking the rest as optional is also a clear trust signal.

Here’s a simple example in TypeScript showing how to inspect the granted scopes after token exchange:

// After exchanging the authorization code for tokens
const grantedScopes = tokenResponse.scope.split(' ');
const requiredScopes = ['read:zones', 'write:zones'];

// Check if all required scopes are present
const hasAllRequired = requiredScopes.every(s => grantedScopes.includes(s));
if (!hasAllRequired) {
  // Handle the case where the user didn't grant all required scopes
  console.warn('User did not grant all required scopes. Adjusting behavior.');
}

Use Cases: MCP Servers and AI Agents

The problem is especially acute for MCP servers. An MCP server might request a broad set of permissions because the agent could theoretically use all features, but most users don’t want to give the agent that much access. Previously, the only solution was for the app developer to build their own scope-selection screen and then send users to Cloudflare’s consent flow. Now, developers can mark some scopes as optional and hand the choice back to the user.

For example, an MCP server that helps manage Cloudflare zones might request read:zones, write:zones, and delete:zones. By marking delete:zones as optional, a user who only wants to read and update settings can uncheck the delete permission, reducing the risk of accidental or malicious deletions.

Limitations and Trade-offs

While this is a welcome improvement, there are some caveats to keep in mind:

• No retroactive changes: Existing clients that don’t adopt optional scopes will continue to work as before, but they won’t benefit from the new flexibility.
• Developer responsibility: The burden is on developers to check the granted scopes and handle partial grants. If an app assumes all requested scopes were granted, it may break or behave unexpectedly.
• Scope evaluation is per request: The optional/required designation only applies to scopes actually requested in a given flow. This means developers need to think carefully about which scopes to request in each flow, not just once at configuration time.
• User education: Users may not understand what it means to uncheck a scope. Clear UI copy and explanations are essential to avoid confusion.

What’s Next and Key Takeaways

Cloudflare says that in the coming weeks, it will expand account- and zone-level role surfaces to nearly all Cloudflare products, meaning more API token roles, account membership options, and OAuth scopes. If you’re building a SaaS integration or an agent, you can try this feature now and adopt the habit of checking actual scopes after authorization.

Key takeaways for product builders:

1. Mark only truly necessary scopes as required. The fewer required scopes, the more likely users are to grant them.
2. Always verify granted scopes after token exchange. Don’t assume the full request was approved.
3. Design your app to work with a subset of permissions. This makes your integration more resilient and user-friendly.
4. Use optional scopes to build trust. Giving users control over permissions signals that you respect their data and security.

By moving from all-or-nothing to task-based consent, Cloudflare is aligning with the broader trend of least-privilege access. For developers, this means building integrations that are flexible enough to work with whatever permissions the user is comfortable granting. It’s a small change with big implications for how we think about OAuth consent in the age of AI agents.

Sources

• Original source

AI-assisted summary compiled from the sources above, reviewed by a human before publishing.