docs(rest): align Roles 'global_access' usage and DELETE-SA token-invalidation status with backend

[nimish-ks]

Summary

Two small corrections found while re-validating the merged feature branch against the current backend (phasehq/console@api--apps-envs-accounts). Stacks under #213.

Roles — request examples sent a rejected key

The POST/PUT examples in roles.mdx shipped "global_access": false inside permissions. The server unconditionally rejects this:

# backend/api/views/roles.py:58
allowed_keys = {"permissions", "app_permissions"}
# → 400 "Unknown top-level keys: global_access. Allowed keys: permissions, app_permissions."

Copy-pasting the docs' cURL or Python snippet failed with 400. Also reconciled the Required-fields / PUT-body prose, which previously said global_access was required — the Note at the top of the page already correctly said only permissions + app_permissions are accepted, so the page now reads consistently.

Service Accounts — DELETE-SA paragraph cited the wrong status code

Delete Service Account said revoked tokens return 403 Forbidden. Actual behaviour is 401 Unauthorized:

# backend/api/auth.py:88-89
if token_is_expired_or_deleted(auth_token):
    raise exceptions.AuthenticationFailed("Token expired or deleted")
# → DRF maps AuthenticationFailed to 401

This matches the sibling Delete Token paragraph (already says 401) and errors.mdx:40. Single-line fix.

Follow-up worth tracking separately (not in this PR)

• Custom-role response omits globalAccess. Per Rohan's comment on PH-618 (May 25), the intent is for globalAccess to be returned on all role responses, including custom roles. Current code only returns it for built-in defaults — verified again today against the dev backend:

  GET /v1/roles/<custom-id>/  →
  {
    ...
    "permissions": {
      "permissions": {...},
      "appPermissions": {...}
      // no "globalAccess" key
    }
  }
  

  The doc examples (POST/PUT response, lines 321 + 436) still show "globalAccess": false on custom roles, which matches Rohan's stated intent. Leaving them unchanged here so the docs reflect intended behaviour; needs a backend tweak so the response actually includes it.

• POST /v1/environments returns 400, PUT returns 409 for the same "name already exists" condition — same error string, different status. Backend fix, not docs. backend/api/utils/environments.py:239 raises ValueError; the POST handler at backend/api/views/environments.py:130-134 blanket-converts to 400, while the PUT handler at line 280 hard-codes 409. 409 is consistent with the Roles duplicate-name behaviour. Will open a separate console PR.

Test plan

• roles.mdx POST cURL example POSTs cleanly against https://localhost/service/public/v1/roles/ (returns 201)
• roles.mdx PUT cURL example PUTs cleanly against an existing custom role (returns 200)
• service-accounts.mdx DELETE paragraph now matches errors.mdx 401 contract
• No other occurrences of global_access left in roles.mdx request payloads (grep -n 'global_access' src/pages/public-api/roles.mdx → only descriptive prose, no example keys)

Related: phasehq/console#798, PH-618

[cloudflare-workers-and-pages]

Deploying phase-docs with    Cloudflare Pages

Latest commit:	712ecdc
Status:	✅  Deploy successful!
Preview URL:	https://c4fab5eb.phase-docs.pages.dev
Branch Preview URL:	https://nimish-ph-618-docs-revalidat.phase-docs.pages.dev

View logs