Document targeting rule permission requirements

content/en/feature_flags/concepts/targeting_rules.md

@@ -30,6 +30,14 @@ Datadog supports different targeting rule types depending on your rollout strate
 | **Progressive rollout** | Randomized rollout over a schedule with multiple steps |
 | **Experiment** | Randomized allocation associated with an experiment |
 
+## Permissions
+
+Creating or editing targeting rules requires the **Feature Flag Write** permission. Changes that create, update, or remove experiment-owned allocation state also require the **Product Analytics Experiments Write** permission. An allocation is experiment-owned when it has a non-empty `experiment_id` or guardrail metrics. A standalone canary allocation or progressive rollout exposure schedule requires only the **Feature Flag Write** permission.
+
+Saving targeting rules replaces the complete allocation set for the flag environment. As a result, the additional permission is required when either the new rules or the existing allocation set contains an experiment-linked or guardrail-backed allocation.
+
+Starting, pausing, resuming, stopping, or deleting a standalone progressive rollout requires the **Feature Flag Write** permission. If the rollout's allocation is experiment-owned, the operation also requires the **Product Analytics Experiments Write** permission.
+
 ## Configure targeting rules
 
 To configure targeting rules for a flag:

content/en/mcp_server/tools.md

@@ -1067,7 +1067,7 @@ Lists allocations for a feature flag in a specific environment.
 
 ### `update_datadog_feature_flag_environment`
 *Toolset: **feature-flags***\
-*Permissions Required: `Feature Flag Environment Read` and `Feature Flag Write`*\
+*Permissions Required: `Feature Flag Environment Read` and `Feature Flag Write`. `Product Analytics Experiments Write` is also required when the environment contains an allocation with a non-empty `experiment_id` or guardrail metrics. Standalone canary allocations and progressive rollout exposure schedules require only `Feature Flag Write`.*\
 Updates a feature flag configuration in a specific environment.
 
 - Enable the `dark-mode` flag in the staging environment.
@@ -1082,7 +1082,7 @@ Checks if a feature flag is implemented in code.
 
 ### `sync_datadog_feature_flag_allocations`
 *Toolset: **feature-flags***\
-*Permissions Required: `Feature Flag Write`*\
+*Permissions Required: `Feature Flag Write`. `Product Analytics Experiments Write` is also required when the request or the existing environment contains an allocation with a non-empty `experiment_id` or guardrail metrics. Standalone canary allocations and progressive rollout exposure schedules require only `Feature Flag Write`.*\
 Syncs feature flag allocations for a specific environment.
 
 - Sync the allocations for flag `new-checkout-flow` in production.

data/api/v2/full_spec.yaml

@@ -140176,6 +140176,10 @@ paths:
     post:
       description: |-
         Pauses a progressive rollout while preserving rollout state.
+
+        This operation requires the **Feature Flag Write** permission. If the rollout's allocation has
+        a non-empty `experiment_id` or guardrail metrics, it also requires the
+        **Product Analytics Experiments Write** permission.
       operationId: PauseExposureSchedule
       parameters:
         - $ref: "#/components/parameters/exposure_schedule_id"
@@ -140243,6 +140247,10 @@ paths:
     post:
       description: |-
         Resumes progression for a previously paused progressive rollout.
+
+        This operation requires the **Feature Flag Write** permission. If the rollout's allocation has
+        a non-empty `experiment_id` or guardrail metrics, it also requires the
+        **Product Analytics Experiments Write** permission.
       operationId: ResumeExposureSchedule
       parameters:
         - $ref: "#/components/parameters/exposure_schedule_id"
@@ -140310,6 +140318,10 @@ paths:
     post:
       description: |-
         Starts a progressive rollout and begins progression.
+
+        This operation requires the **Feature Flag Write** permission. If the rollout's allocation has
+        a non-empty `experiment_id` or guardrail metrics, it also requires the
+        **Product Analytics Experiments Write** permission.
       operationId: StartExposureSchedule
       parameters:
         - $ref: "#/components/parameters/exposure_schedule_id"
@@ -140377,6 +140389,10 @@ paths:
     post:
       description: |-
         Stops a progressive rollout and marks it as aborted.
+
+        This operation requires the **Feature Flag Write** permission. If the rollout's allocation has
+        a non-empty `experiment_id` or guardrail metrics, it also requires the
+        **Product Analytics Experiments Write** permission.
       operationId: StopExposureSchedule
       parameters:
         - $ref: "#/components/parameters/exposure_schedule_id"
@@ -140659,6 +140675,12 @@ paths:
     post:
       description: |-
         Creates a new targeting rule (allocation) for a specific feature flag in a specific environment.
+
+        This operation requires the **Feature Flag Write** permission. Creating experiment-owned allocation
+        state also requires the **Product Analytics Experiments Write** permission. An allocation is
+        experiment-owned when it has a non-empty `experiment_id` or `guardrail_metrics`. A standalone
+        `CANARY` allocation or progressive `exposure_schedule` requires only the **Feature Flag Write**
+        permission.
       operationId: CreateAllocationsForFeatureFlagInEnvironment
       parameters:
         - $ref: "#/components/parameters/feature_flag_id"
@@ -140779,6 +140801,13 @@ paths:
       description: |-
         Updates targeting rules (allocations) for a specific feature flag in a specific environment.
         This operation replaces the existing allocation set with the request payload.
+
+        This operation requires the **Feature Flag Write** permission. Updating or removing experiment-owned
+        allocation state also requires the **Product Analytics Experiments Write** permission. An allocation is
+        experiment-owned when it has a non-empty `experiment_id` or `guardrail_metrics`. A standalone `CANARY`
+        allocation or progressive `exposure_schedule` requires only the **Feature Flag Write** permission.
+        Because this operation replaces the complete allocation set, the additional permission is required when
+        either the request or the existing allocation set contains experiment-owned state.
       operationId: UpdateAllocationsForFeatureFlagInEnvironment
       parameters:
         - $ref: "#/components/parameters/feature_flag_id"

data/api/v2/translate_actions.json

@@ -1875,19 +1875,19 @@
     "request_schema_description": "Request to update an environment."
   },
   "PauseExposureSchedule": {
-    "description": "Pauses a progressive rollout while preserving rollout state.",
+    "description": "Pauses a progressive rollout while preserving rollout state.\n\nThis operation requires the **Feature Flag Write** permission. If the rollout's allocation has\na non-empty `experiment_id` or guardrail metrics, it also requires the\n**Product Analytics Experiments Write** permission.",
     "summary": "Pause a progressive rollout"
   },
   "ResumeExposureSchedule": {
-    "description": "Resumes progression for a previously paused progressive rollout.",
+    "description": "Resumes progression for a previously paused progressive rollout.\n\nThis operation requires the **Feature Flag Write** permission. If the rollout's allocation has\na non-empty `experiment_id` or guardrail metrics, it also requires the\n**Product Analytics Experiments Write** permission.",
     "summary": "Resume a progressive rollout"
   },
   "StartExposureSchedule": {
-    "description": "Starts a progressive rollout and begins progression.",
+    "description": "Starts a progressive rollout and begins progression.\n\nThis operation requires the **Feature Flag Write** permission. If the rollout's allocation has\na non-empty `experiment_id` or guardrail metrics, it also requires the\n**Product Analytics Experiments Write** permission.",
     "summary": "Start a progressive rollout"
   },
   "StopExposureSchedule": {
-    "description": "Stops a progressive rollout and marks it as aborted.",
+    "description": "Stops a progressive rollout and marks it as aborted.\n\nThis operation requires the **Feature Flag Write** permission. If the rollout's allocation has\na non-empty `experiment_id` or guardrail metrics, it also requires the\n**Product Analytics Experiments Write** permission.",
     "summary": "Stop a progressive rollout"
   },
   "GetFeatureFlag": {
@@ -1905,13 +1905,13 @@
     "summary": "Archive a feature flag"
   },
   "CreateAllocationsForFeatureFlagInEnvironment": {
-    "description": "Creates a new targeting rule (allocation) for a specific feature flag in a specific environment.",
+    "description": "Creates a new targeting rule (allocation) for a specific feature flag in a specific environment.\n\nThis operation requires the **Feature Flag Write** permission. Creating experiment-owned allocation\nstate also requires the **Product Analytics Experiments Write** permission. An allocation is\nexperiment-owned when it has a non-empty `experiment_id` or `guardrail_metrics`. A standalone\n`CANARY` allocation or progressive `exposure_schedule` requires only the **Feature Flag Write**\npermission.",
     "summary": "Create targeting rules for a flag env",
     "request_description": "",
     "request_schema_description": "Request to create targeting rules (allocations) for a feature flag in an environment."
   },
   "UpdateAllocationsForFeatureFlagInEnvironment": {
-    "description": "Updates targeting rules (allocations) for a specific feature flag in a specific environment.\nThis operation replaces the existing allocation set with the request payload.",
+    "description": "Updates targeting rules (allocations) for a specific feature flag in a specific environment.\nThis operation replaces the existing allocation set with the request payload.\n\nThis operation requires the **Feature Flag Write** permission. Updating or removing experiment-owned\nallocation state also requires the **Product Analytics Experiments Write** permission. An allocation is\nexperiment-owned when it has a non-empty `experiment_id` or `guardrail_metrics`. A standalone `CANARY`\nallocation or progressive `exposure_schedule` requires only the **Feature Flag Write** permission.\nBecause this operation replaces the complete allocation set, the additional permission is required when\neither the request or the existing allocation set contains experiment-owned state.",
     "summary": "Update targeting rules for a flag",
     "request_description": "",
     "request_schema_description": "Request to overwrite targeting rules (allocations) for a feature flag in an environment."
@@ -6936,4 +6936,4 @@
     "description": "Cancels a specific execution of a given workflow. This API requires a [registered application key](https://docs.datadoghq.com/api/latest/action-connection/#register-a-new-app-key). Alternatively, you can configure these permissions [in the UI](https://docs.datadoghq.com/account_management/api-app-keys/#actions-api-access).",
     "summary": "Cancel a workflow instance"
   }
-}
+}