up

docs/api/policy.md

@@ -10,7 +10,7 @@ This document is the canonical reference for the Policy Engine REST surface desc
 ## 1 · Authentication & Headers
 
 - **Auth:** Bearer tokens (`Authorization: Bearer <token>`) with the following scopes as applicable:
-  - `policy:read`, `policy:write`, `policy:submit`, `policy:approve`, `policy:run`, `policy:activate`, `policy:archive`, `policy:simulate`, `policy:runs`
+- `policy:read`, `policy:author`, `policy:review`, `policy:approve`, `policy:operate`, `policy:run`, `policy:activate`, `policy:archive`, `policy:simulate`, `policy:runs`
   - `findings:read` (for effective findings APIs)
   - `effective:write` (service identity only; not exposed to clients)
 - **Service identity:** Authority marks the Policy Engine client with `properties.serviceIdentity: policy-engine`. Tokens missing this marker cannot obtain `effective:write`.
@@ -53,7 +53,7 @@ All errors use HTTP semantics plus a structured payload:
 
 ```
 POST /api/policy/policies
-Scopes: policy:write
+Scopes: policy:author
 ```
 
 **Request**
@@ -106,7 +106,7 @@ Returns full DSL, metadata, provenance, simulation artefact references.
 
 ```
 PUT /api/policy/policies/{policyId}/versions/{version}
-Scopes: policy:write
+Scopes: policy:author
 ```
 
 Body identical to create. Only permitted while `status=draft`.
@@ -119,7 +119,7 @@ Body identical to create. Only permitted while `status=draft`.
 
 ```
 POST /api/policy/policies/{policyId}/versions/{version}:submit
-Scopes: policy:submit
+Scopes: policy:author
 ```
 
 **Request**
@@ -196,7 +196,7 @@ Request includes `reason` and optional `incidentId`.
 
 ```
 POST /api/policy/policies/{policyId}/versions/{version}:compile
-Scopes: policy:write
+Scopes: policy:author
 ```
 
 **Response 200**
@@ -221,7 +221,7 @@ Scopes: policy:write
 
 ```
 POST /api/policy/policies/{policyId}/lint
-Scopes: policy:write
+Scopes: policy:author
 ```
 
 Slim wrapper used by CLI; returns 204 on success or `ERR_POL_001` payload.