ref(api): document helper permission intent

Keep replay summary POST on read-level replay scopes and mark it as an explicit readonly-mutation exception, since it derives summary data from existing replay/event data.

Document the preview endpoints that intentionally keep write-aligned permissions because they are part of alert and monitor authoring flows, even though they use POST helper endpoints.

Add replay summary token tests covering the read-scope contract.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: dcramer

src/sentry/replays/endpoints/project_replay_summary.py

@@ -39,7 +39,7 @@
 class ReplaySummaryPermission(ProjectPermission):
     scope_map = {
         "GET": ["event:read", "event:write", "event:admin"],
-        "POST": ["event:write", "event:admin"],
+        "POST": ["event:read", "event:write", "event:admin"],
         "PUT": [],
         "DELETE": [],
     }
@@ -52,6 +52,13 @@ class ProjectReplaySummaryEndpoint(ProjectReplayEndpoint):
         "GET": ApiPublishStatus.EXPERIMENTAL,
         "POST": ApiPublishStatus.EXPERIMENTAL,
     }
+    readonly_mutation_scope_exceptions = {
+        "POST": (
+            "POST starts replay-summary generation but only derives summary data from existing "
+            "replay/event data. It intentionally follows replay read access instead of requiring "
+            "a separate write capability."
+        )
+    }
     permission_classes = (ReplaySummaryPermission,)
 
     def __init__(self, **kw) -> None:

src/sentry/seer/endpoints/organization_events_anomalies.py

@@ -33,6 +33,8 @@ class OrganizationEventsAnomaliesEndpoint(OrganizationEventsEndpointBase):
     publish_status = {
         "POST": ApiPublishStatus.EXPERIMENTAL,
     }
+    # This POST previews anomaly-detection config used while authoring metric
+    # alerts/detectors, so it intentionally follows alert-write permissions.
     permission_classes = (OrganizationAlertRulePermission,)
 
     @extend_schema(

src/sentry/uptime/endpoints/organization_uptime_alert_preview_check.py

@@ -30,6 +30,8 @@
 @cell_silo_endpoint
 class OrganizationUptimeAlertPreviewCheckEndpoint(OrganizationEndpoint):
     owner = ApiOwner.CRONS
+    # This POST previews monitor creation and validation, so it intentionally
+    # uses the same permission surface as creating the alert itself.
     permission_classes = (OrganizationAlertRulePermission,)
 
     publish_status = {

src/sentry/uptime/endpoints/organization_uptime_assertion_suggestions.py

@@ -50,6 +50,8 @@ class OrganizationUptimeAssertionSuggestionsEndpoint(OrganizationEndpoint):
     """
 
     owner = ApiOwner.CRONS
+    # This POST is part of the uptime monitor authoring flow, so it should
+    # track the same alert-write permission as the monitor it helps create.
     permission_classes = (OrganizationAlertRulePermission,)
 
     publish_status = {

tests/sentry/replays/endpoints/test_project_replay_summary.py

@@ -7,8 +7,11 @@
 from django.conf import settings
 from django.urls import reverse
 
+from sentry.models.apitoken import ApiToken
 from sentry.replays.testutils import mock_replay
+from sentry.silo.base import SiloMode
 from sentry.testutils.cases import SnubaTestCase, TransactionTestCase
+from sentry.testutils.silo import assume_test_silo_mode
 from sentry.utils import json
 
 
@@ -140,6 +143,41 @@ def test_post_simple(self, mock_seer_request: Mock) -> None:
         assert body["project_id"] == self.project.id
         assert body.get("temperature") is None
 
+    @patch("sentry.replays.endpoints.project_replay_summary.make_replay_summary_start_request")
+    def test_post_allows_event_read_scope_for_api_tokens(self, mock_seer_request: Mock) -> None:
+        mock_seer_request.return_value = MockSeerResponse(200, json_data={"hello": "world"})
+        self.store_replay()
+
+        with assume_test_silo_mode(SiloMode.CONTROL):
+            token = ApiToken.objects.create(user=self.user, scope_list=["event:read"])
+
+        with self.feature(self.features):
+            response = self.client.post(
+                self.url,
+                data={"num_segments": 1},
+                content_type="application/json",
+                HTTP_AUTHORIZATION=f"Bearer {token.token}",
+            )
+
+        assert response.status_code == 200
+        assert response.json() == {"hello": "world"}
+
+    def test_post_requires_replay_read_scope_for_api_tokens(self) -> None:
+        self.store_replay()
+
+        with assume_test_silo_mode(SiloMode.CONTROL):
+            token = ApiToken.objects.create(user=self.user, scope_list=["org:read"])
+
+        with self.feature(self.features):
+            response = self.client.post(
+                self.url,
+                data={"num_segments": 1},
+                content_type="application/json",
+                HTTP_AUTHORIZATION=f"Bearer {token.token}",
+            )
+
+        assert response.status_code == 403
+
     def test_post_replay_not_found(self) -> None:
         with self.feature(self.features):
             response = self.client.post(