Cloudflare’s third-party OAuth platform has seen significant adoption since launching in June, with developers building thousands of apps and users completing more than a million authorizations. OAuth enables delegated access, letting applications act on a user’s behalf without exposing passwords or long-lived credentials. The model works well when an app can summarize its needs in a small set of scopes, but as developers use OAuth for SaaS integrations, internal tools, CLIs, and agents, permission requirements have become more granular. That granularity makes a purely binary consent screen increasingly difficult to justify.

Cloudflare OAuth already allowed clients to request a subset of their configured scopes. However, once a request was made, users had no way to narrow it during consent. The screen remained all-or-nothing: approve the full request or deny it. For example, an MCP server might request a broad set of permissions because an agent could theoretically use all of them, but most users would not want to grant an agent that much access. Previously, the only workaround was for the developer to build a custom scope-selection screen before redirecting users to Cloudflare’s consent flow.

Today, Cloudflare is introducing OAuth scope customization. Client owners can mark specific scopes as optional when configuring an OAuth client, allowing users to grant a narrower subset of the application’s requested access during authorization. This builds on the OAuth specification’s existing flexibility, which already permits authorization servers to grant a smaller scope set than the one requested.

The goal is to give security-conscious users more control without converting the consent screen into a lengthy checklist. With scope customization:

  • Developers can mark scopes on an OAuth client as required or optional
  • Users can deselect optional scopes from the requested set during authorization
  • Required and optional scopes are evaluated against the scopes requested for that specific flow
  • The consent experience is unchanged when no optional scopes appear in the request
  • By default, the consent screen grants the full requested scope set

Scope checks stay tied to the current request

A key detail is that required and optional designations are evaluated only against the scopes requested in a given authorization flow, not against the full set of scopes configured on the client. This distinction matters because OAuth clients do not always request their entire configured scope set.

Consider a client configured with user-details.read, workers-scripts.write, workers-kv-storage.write, and zone.read, with the last two marked optional. If the client starts an authorization flow requesting all four scopes, the consent screen evaluates all four: user-details.read and workers-scripts.write stay required, while the user can choose whether to grant workers-kv-storage.write and zone.read.

If that same client later requests only workers-scripts.write and zone.read, only those two are considered in that flow. user-details.read and workers-kv-storage.write would not be shown or enforced because they were not requested. This keeps the consent screen focused on the task at hand and preserves existing behavior for clients that do not opt into optional scopes.

Configuring optional scopes

Developers opt into customization when configuring an OAuth client. Scopes are configured as before, with an additional setting to designate which are optional:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "client_name": "ACME Corp",
    "redirect_uris": [
      "https://acme.org/oauth/callback"
    ],
    "grant_types": [
      "authorization_code"
    ],
    "response_types": [
      "code"
    ],
    "token_endpoint_auth_method": "client_secret_basic",
    "scopes": [
      "user-details.read",
      "workers-scripts.write",
      "workers-kv-storage.write",
      "zone.read"
    ],
    "optional_scopes": [
      "workers-kv-storage.write",
      "zone.read"
    ]
  }'

In that configuration, a client can request all four scopes, but users can only opt out of workers-kv-storage.write and zone.read. The others remain required when included in an authorization request. If the client requests only a subset, the optional flags for unrequested scopes have no effect.

Handling partial grants

When a user deselects optional scopes and completes authorization, the resulting access token contains only the scopes they consented to. Developers must check the granted scope set after exchanging the authorization code rather than assuming the full request was approved.

Apps that handle narrower grants gracefully — for instance, an agent that operates within whatever permission subset it receives — are more likely to earn user trust. Requesting only necessary permissions and marking the rest optional signals that the application respects the user’s access decisions.

Broader scope coverage on the way

Over the coming weeks, Cloudflare will expand its account- and zone-level role surface to cover nearly every product. This means more API token roles, account membership options, and OAuth scopes, giving customers finer-grained tools for securing workloads.

Optional OAuth scopes give developers more nuanced control over authorization flows and give users more say in what they approve. Developers can get started through the OAuth documentation or by creating an app on the OAuth clients page in the dashboard.