[Fundamentals] Document optional OAuth scopes (#32557)

* [Fundamentals] Document optional OAuth scopes

* [Fundamentals] Add documentation for the bulk selection buttons when authorizing an OAuth application

* update changelog

* updating styling for bulleted items

* fix file name date

---------

Co-authored-by: Adam Bouhmad <adbouhmad@gmail.com>

Author: itaquito

src/content/changelog/fundamentals/2026-08-20-oauth-optional-scopes.mdx

@@ -0,0 +1,23 @@
+---
+title: Optional OAuth scopes
+description: OAuth clients can now mark scopes as required or optional
+products:
+  - fundamentals
+date: 2026-08-20
+---
+
+We're announcing the GA of Optional OAuth Scopes. 
+
+OAuth client developers can now classify configured scopes as required or optional in the Cloudflare dashboard. By default, all configured scopes remain required .
+
+## What's New
+
+**Optional Scopes:** OAuth clients can now mark configured scopes as optional, allowing applications to request them without requiring users to approve them.
+
+**Scope Selection:** On the consent screen, users must grant required scopes but can decline optional scopes. This helps customers apply least-privilege access to applications, CLIs, and workloads. Optional scopes are selected by default.
+
+**Templates:** The consent screen now includes **Read Only** and **Full Access** templates to make scope selection faster and easier.  
+
+**Search:** Users can now search scopes in the consent screen.
+
+Learn how to [select client scopes](/fundamentals/oauth/create-an-oauth-client/#select-scopes) and [edit optional permissions](/fundamentals/oauth/authorizing-an-application/#edit-optional-permissions).

src/content/docs/fundamentals/oauth/authorizing-an-application.mdx

@@ -9,7 +9,7 @@ products:
   - oauth
 ---
 
-import { DashButton } from "~/components";
+import { DashButton, Steps } from "~/components";
 
 ## Overview
 
@@ -22,7 +22,7 @@ When a third-party application requests access to your Cloudflare account, you w
 - **Application name and logo**: The name and branding of the requesting application
 - **Publisher domain**: The domain and verification status of the application publisher
 - **Account selection**: Choose which Cloudflare account(s) the application can access
-- **Requested permissions**: After selecting the account(s) the application may access, the specific scopes the application is requesting will be displayed before consent is complete. To finish the authorization process, review the permissions the application is requesting and click “**Authorize**”
+- **Requested permissions**: After selecting the account(s) the application may access, the specific scopes the application is requesting will be displayed before consent is complete. You can also decline optional permissions. To finish the authorization process, review the permissions the application is requesting and select “**Authorize**”
 
 Each shield icon indicates who owns the application and whether its domain ownership is verified:
 
@@ -32,14 +32,26 @@ Each shield icon indicates who owns the application and whether its domain owner
 
 Domain verification only confirms that the application owner controls the displayed domain.
 
+### Edit optional permissions
+
+All requested permissions are selected by default. You can turn off optional permissions, but required permissions remain selected. Select **Read only** to include only optional scopes with read access, or **Full access** to include all optional scopes. If the client has no permissions configured as optional, editing controls do not appear.
+
+<Steps>
+	1. In **Additional access**, select **Edit Permissions**.
+	2. Turn permissions on or off individually or by category.
+	3. Select **Authorize** to grant required and selected optional permissions.
+</Steps>
+
 ## View and revoke authorized applications
 
 Application authorizations may be viewed and revoked at any time from the profile page on the Cloudflare dashboard.
 
-1. Log in to the Cloudflare dashboard.
-2. <DashButton url="/?to=/profile/access-management/authorization" />
-3. View the list of applications you have authorized.
-   - If you wish to revoke access to an application, click the “Revoke” button for that row
+<Steps>
+	1. Log in to the Cloudflare dashboard.
+	2. <DashButton url="/?to=/profile/access-management/authorization" />
+	3. View the list of applications you have authorized.
+	   - If you wish to revoke access to an application, select the “Revoke” button for that row
+</Steps>
 
 ## Account administrator controls
 

src/content/docs/fundamentals/oauth/create-an-oauth-client.mdx

@@ -30,8 +30,9 @@ To create an OAuth client, you must have one of these roles for the associated a
 				- Redirect URLs
 			6. Optional: Add non-required fields.
 			7. Select **Continue** and define the scopes required for your client.
-			8. Select **Create client**.
-			9. Save your **Client ID** and **Client Secret** in a secure location.
+			8. Optional: In **Choose optional scopes**, turn off **Required** for each scope you want to make optional. All scopes are required by default.
+			9. Select **Create client**.
+			10. Save your **Client ID** and **Client Secret** in a secure location.
 		</Steps>
 
 		<DashButton url="/?to=/:account/oauth-clients" />
@@ -47,7 +48,8 @@ To create an OAuth client, you must have one of these roles for the associated a
 				"client_name": "Cloudflare OAuth Client",
 				"grant_types": ["authorization_code"],
 				"redirect_uris": ["https://example.com/oauth/callback"],
-				"scopes": ["workers-platform.read"],
+				"scopes": ["workers-platform.read", "workers-platform.write"],
+				"optional_scopes": ["workers-platform.read"],
 				"post_logout_redirect_uris": ["https://example.com/logout"],
 				"response_types": ["code"],
 				"token_endpoint_auth_method": "client_secret_basic",
@@ -71,7 +73,11 @@ OAuth scope names correspond to Cloudflare API token permission names. Use the C
 
 <Tabs syncKey="dashPlusAPI">
 	<TabItem label="Dashboard">
-		When you create or edit an OAuth client, all available scopes are displayed. Search for and select the scopes required for your client.
+		When you create or edit an OAuth client, select at least one scope. All selected scopes are required by default.
+
+		In **Choose optional scopes**, turn off **Required** for each scope you want to make optional.
+
+		Required scopes must be granted on the consent screen, while optional scopes can be declined by the user.
 	</TabItem>
 	<TabItem label="API">
 		Fetch the available scopes from the API. Use the scope ID when you create a client through the API.
@@ -81,6 +87,8 @@ OAuth scope names correspond to Cloudflare API token permission names. Use the C
 			-H "Content-Type: application/json" \
 			-H "Authorization: Bearer $API_TOKEN"
 		```
+		
+		To mark scopes as optional, include them in the `optional_scopes` of the request. This must be a subset of the `scopes` for the client. Optional scopes may be declined by the user during authorization.
 	</TabItem>
 </Tabs>