Cloudflare Optional OAuth Scopes Let Developers Gate What Users May Drop

Cloudflare has added optional OAuth scopes, giving developers a mechanism to designate which permissions a user may deselect at the consent screen rather than forcing an all-or-nothing decision. The company's stated motivation is Model Context Protocol servers: an MCP integration may exercise a wide range of capabilities, yet most users would resist handing an agent the full union of those permissions upfront. The feature lands at a moment when infrastructure governance decisions around agent deployment are increasingly where security risk is decided.

The underlying problem is structural. A conventional OAuth client with a handful of scopes produces a consent screen a user can reason about. An agent-backed MCP server requesting permissions for every action it might ever take cannot. An agent that reads inventory to compare products does not need price-write access. One verifying order status does not need authority to issue refunds. One querying supplier records during research does not need payment access. Without optional scopes, the consent screen asks the user to approve all of it simultaneously or walk away.

How the Configuration Works

Client owners mark optional permissions using an optional_scopes array alongside the standard scopes list at OAuth client configuration time:

"scopes": [
  "user-details.read",
  "workers-scripts.write",
  "workers-kv-storage.write",
  "zone.read"
],
"optional_scopes": [
  "workers-kv-storage.write",
  "zone.read"
]

A critical behavioral constraint governs evaluation: required and optional scopes are checked against what the client requests in a specific authorization flow, not against everything configured on the client. A client configured with four scopes that initiates a flow requesting only two presents the user with only those two. Clients that do not populate optional_scopes retain existing behavior — the consent screen grants the full requested set. Marking a scope required prevents a user from removing something the application genuinely needs to function, which is a materially different guarantee from hoping users do not deselect critical permissions.

Runtime Consequences for Application Code

When a user deselects an optional scope, the resulting access token carries only the granted subset. Applications must inspect the scope parameter in the token response after exchanging the authorization code — code written assuming that a successful exchange implies everything requested will encounter authorization errors on calls it expected to succeed. Cloudflare's guidance is to degrade gracefully rather than surface raw 403 errors: an application that loses a write scope should disable that feature and communicate the reduced capability to the user.

For MCP server design, this maps to a concrete pattern: require read access for whatever the agent queries by default, mark write access optional, check the granted scope set before attempting any mutation, and halt cleanly when authority is absent. An agent that can read a team's Workers scripts and write to them only when a user explicitly permits it at consent time presents a structurally different capability verification profile than one demanding full write access at first contact.

Cloudflare vs. Existing Partial-Consent Implementations

Partial consent exists elsewhere, but implementations differ in which party controls which scopes are droppable.

The differentiating property is developer-declared optionality: required scopes cannot be removed regardless of user preference, while optional ones remain entirely the user's call at consent time.

Broader MCP Authorization Context

None of this required amending OAuth. RFC 6749 has always permitted an authorization server to issue a token scoped more narrowly than the client requested. What is changing is that providers are surfacing that latitude directly in the consent interface, precisely as MCP deployments make broad permission requests routine. The MCP specification revision dated 2026-07-28 tightened client authorization separately, preferring pre-registered clients and Client ID Metadata Documents while deprecating Dynamic Client Registration. Microsoft's hosted Azure DevOps MCP Server reached general availability without supporting Claude, ChatGPT, or Cursor because Entra lacks the client registration mechanisms those clients require. Optional scopes address a third distinct layer: not agent identity, not which clients may connect, but how much access a user must surrender to let an agent operate at all.

Cloudflare reports more than one million authorizations across thousands of third-party OAuth apps created since June, and says it will extend account- and zone-level roles to cover nearly every product in the coming weeks, adding API token roles, account membership options, and OAuth scopes alongside. The consent screen has historically been a binary gate; the tooling is now catching up to the reality that agentic systems require layered, negotiable permission surfaces rather than monolithic approval.