From 712ecdcd36c62e8e31552f247afd00136c6704ab Mon Sep 17 00:00:00 2001
From: Nimish <nimish@phase.dev>
Date: Tue, 26 May 2026 23:27:55 +0530
Subject: [PATCH] docs(rest): align Roles 'global_access' and SA-delete status
 code with backend

After re-validation against `phasehq/console@api--apps-envs-accounts`:

- Roles POST/PUT examples shipped `"global_access": false`, but the
  server rejects any `global_access` / `globalAccess` under `permissions`
  with `400 Bad Request` (`backend/api/views/roles.py:58`, allowed_keys =
  {"permissions", "app_permissions"}). Removed the rejected key from
  both cURL + Python examples and rewrote the Required-fields /
  PUT-body descriptions to match. The Note block at the top of the
  page (line 60) already said only `permissions` + `app_permissions`
  are accepted, so the page is now internally consistent.

- DELETE Service Account paragraph said revoked tokens return
  `403 Forbidden`. Actual behaviour is `401 Unauthorized` with
  `{"error": "Token expired or deleted"}`
  (`backend/api/auth.py:88-89` raises `AuthenticationFailed`, which DRF
  maps to 401). Matches the sibling DELETE Token paragraph and
  `errors.mdx` line 40.

Related: phasehq/console#798, PH-618
---
 src/pages/public-api/roles.mdx            | 11 ++++-------
 src/pages/public-api/service-accounts.mdx |  2 +-
 2 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/src/pages/public-api/roles.mdx b/src/pages/public-api/roles.mdx
index 077046a..1fcf5f4 100644
--- a/src/pages/public-api/roles.mdx
+++ b/src/pages/public-api/roles.mdx
@@ -222,7 +222,7 @@ Responses use camelCase keys (`appPermissions`, `globalAccess`). On POST and PUT
         The role name. Maximum 64 characters. Must be unique within the organisation (case-insensitive).
       </Property>
       <Property name="permissions" type="object">
-        The permissions object. Must include `permissions` (org-level), `app_permissions` (app-level), and `global_access` (boolean).
+        The permissions object. Must contain exactly two keys: `permissions` (org-level) and `app_permissions` (app-level). The `global_access` flag cannot be set on custom roles — POST and PUT reject requests that include `global_access` (or `globalAccess`) under `permissions` with `400 Bad Request`.
       </Property>
     </Properties>
 
@@ -260,8 +260,7 @@ Responses use camelCase keys (`appPermissions`, `globalAccess`). On POST and PUT
           "app_permissions": {
             "Secrets": ["read"],
             "Environments": ["read"]
-          },
-          "global_access": false
+          }
         }
       }'
     ```
@@ -289,7 +288,6 @@ Responses use camelCase keys (`appPermissions`, `globalAccess`). On POST and PUT
                 'Secrets': ['read'],
                 'Environments': ['read'],
             },
-            'global_access': False,
         }
     }
 
@@ -345,7 +343,7 @@ Responses use camelCase keys (`appPermissions`, `globalAccess`). On POST and PUT
 
     ### JSON Body
 
-    When `permissions` is provided, the full object replaces the stored permissions and must contain all three keys: `permissions`, `app_permissions`, and `global_access`. The camelCase variants `appPermissions` and `globalAccess` are also accepted on input.
+    When `permissions` is provided, the full object replaces the stored permissions and must contain exactly two keys: `permissions` and `app_permissions`. The camelCase variant `appPermissions` is also accepted on input. Sending `global_access` (or `globalAccess`) under `permissions` returns `400 Bad Request`.
 
     <Properties>
       <Property name="name" type="string">
@@ -386,8 +384,7 @@ Responses use camelCase keys (`appPermissions`, `globalAccess`). On POST and PUT
             "Secrets": ["read"],
             "Environments": ["read"],
             "Logs": ["read"]
-          },
-          "global_access": false
+          }
         }
       }'
     ```
diff --git a/src/pages/public-api/service-accounts.mdx b/src/pages/public-api/service-accounts.mdx
index 256fa09..1a6b84d 100644
--- a/src/pages/public-api/service-accounts.mdx
+++ b/src/pages/public-api/service-accounts.mdx
@@ -377,7 +377,7 @@ When fetching a single service account, additional detail fields are included:
 <Row>
   <Col>
 
-    Delete a service account. All associated tokens are immediately invalidated (subsequent requests with those tokens return `403 Forbidden`), and all app/environment access grants are removed.
+    Delete a service account. All associated tokens are immediately invalidated (subsequent requests with those tokens return `401 Unauthorized` with `{"error": "Token expired or deleted"}`), and all app/environment access grants are removed.
 
     ### URL parameters