[Fundamentals] Document optional OAuth scopes

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

@@ -0,0 +1,13 @@
+---
+title: Optional OAuth scopes
+description: OAuth clients can now classify scopes as required or optional.
+products:
+  - fundamentals
+date: 2026-08-06
+---
+
+OAuth client developers can classify configured scopes as required or optional in the dashboard. All configured scopes remain required by default.
+
+On consent screens, users must grant required permissions but can decline optional permissions. Optional permissions are selected by default, so users only customize them when needed.
+
+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. If no optional permissions are requested, 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.