### Introducing OAuth Scope Customization on Cloudflare
At Cloudflare, we are constantly working to enhance security and give users more control over their data. As part of this effort, we are excited to introduce **OAuth scope customization**, a new feature designed to provide developers and users with greater flexibility when managing delegated access.
Since June, thousands of third‑party OAuth applications have been built on Cloudflare, resulting in more than a million authorizations. OAuth enables delegated access, allowing applications to act on a user’s behalf without requiring long‑lived credentials or passwords. Traditionally, these permissions have been managed through scopes—predefined permissions that specify what an application is allowed to do.
Over time, our permission model has become more granular to support a wide range of use cases, including SaaS integrations, internal tools, command‑line interfaces, and autonomous agents. While this granularity improves security, it also makes a strict “all‑or‑nothing” consent model difficult to justify. Many applications request broad permissions, but users may only wish to grant a subset of those permissions based on their comfort level and use case.
To address this challenge, we are now giving users more control at the authorization stage. With OAuth scope customization, developers can mark certain scopes as optional, allowing users to selectively approve only the permissions their application truly needs.
### More Control, Without Overwhelming Users
Our goal with this feature is to empower security‑conscious users to make informed decisions without complicating the consent experience. Scope customization provides flexibility while keeping the interface simple:
– Developers define which scopes are required and which are optional during client configuration.
– At authorization time, users can deselect optional scopes they do not wish to grant.
– Required scopes remain mandatory and are always presented to the user.
– If no optional scopes are requested, the behavior remains consistent with the existing consent flow.
– By default, the consent screen still grants the full requested scope set unless the user chooses to narrow it.
This approach ensures that users are not overwhelmed by unnecessary permissions while maintaining a smooth experience for applications with minimal scope requirements.
### Scoping to the Authorization Request
One important aspect of scope evaluation is that required and optional scopes are only assessed against the scopes explicitly requested in a given authorization flow—not every scope configured on the client. This design allows for greater flexibility:
– A client may be configured with multiple scopes but only request a subset during a specific flow.
– Only the scopes included in that request are subject to evaluation.
– Required and optional scopes are enforced relative to what is requested.
For example, if an application requests `user-details.read`, `workers-scripts.write`, `workers-kv-storage.write`, and `zone.read`, and marks the last two as optional, the user can choose whether to grant `workers-kv-storage.write` and `zone.read`. If later the client requests only `workers-scripts.write` and `zone.read`, the other scopes are not considered at all.
This keeps the consent screen focused and context‑driven, while ensuring that existing clients continue to behave as before unless they opt into the new functionality.
### Configuring an OAuth Client to Use Optional Scopes
Developers can enable scope customization when configuring an OAuth client. Scopes are defined as usual, with the addition of an `optional_scopes` parameter that specifies which scopes users may deselect:
“`bash
curl
–request POST
–header “Authorization: Bearer $CLOUDFLARE_API_TOKEN”
–header “Content-Type: application/json”
–data ‘{
“client_name”: “ACME Corp”,
“redirect_uris”: [“”],
“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 this example, users can choose to decline `workers-kv-storage.write` and `zone.read` during consent, while still being required to approve `user-details.read` and `workers-scripts.write` if those scopes are part of the authorization request.
### Building with Partial Grants in Mind
When users decline optional scopes and complete the authorization flow, the resulting access token includes only the permissions they approved. For developers, this means always checking the granted scope set after exchanging the authorization code, rather than assuming all requested scopes were approved.
Applications that gracefully handle narrower permissions—for example, agents that operate within whatever access they receive—are more trustworthy and respectful of user choices. Clearly marking scopes as optional signals to users that your application respects their decisions and minimizes unnecessary risk.
### Scope Support Across Cloudflare Products
Over the coming weeks, Cloudflare will continue expanding role and scope support across its product suite. This includes new API token roles, account membership options, and OAuth scopes designed to give customers fine‑grained control over their workloads.
### Build with Optional Scopes
Optional OAuth scopes represent an important step toward a more flexible and trustworthy consent experience on Cloudflare. Developers can build more nuanced authorization flows, while users gain greater control over what they approve.
To get started with third‑party OAuth applications, refer to our [documentation](#) or visit the OAuth apps page in the Cloudflare dashboard to create your first OAuth client.
We would also like to thank our interns who helped bring this feature to life—including Miller Vargas from the University of Texas at Austin and José Enrique Rodriguez from Universidad Panamericana—for their contributions to this release.
—
### FAQ
**What is OAuth scope customization?**
OAuth scope customization allows developers to designate certain permissions as optional. During authorization, users can choose to grant only the optional scopes they are comfortable with, rather than approving all requested permissions at once.
**How does this affect existing OAuth applications?**
Existing applications will continue to work exactly as before. Optional scope functionality is opt‑in, so developers must explicitly mark scopes as optional for the new behavior to apply.
**Can users change their mind after granting access?**
OAuth tokens are issued based on the scopes approved during authorization. If a user deselects optional scopes before completing consent, the resulting token will only include the selected permissions.
**Do optional scopes appear differently in the consent screen?**
Optional scopes may be presented with clear indicators so users can easily identify and deselect them. Required scopes remain mandatory and are always included in the consent prompt.
**Will this change how tokens are validated?**
Token validation remains unchanged. Applications should always verify the granted scopes within the token and ensure they handle cases where fewer permissions than expected are provided.
—
### Conclusion
OAuth scope customization enhances user control and trust by giving users the ability to tailor application permissions to their specific needs. For developers, this feature enables more flexible and respectful authorization flows, while maintaining strong security standards. By combining required and optional scopes, Cloudflare continues to evolve its platform in a way that balances usability, transparency, and security. We encourage all developers to explore this feature and build more granular, user‑centric experiences on Cloudflare.
