diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx
index ea39d3a..bfb38a3 100644
--- a/api-reference/error-codes.mdx
+++ b/api-reference/error-codes.mdx
@@ -64,6 +64,7 @@ Every code on this page is one `agentsfleetd` can actually emit — the list is
 | `UZ-AUTH-006` | 401 | Session expired | Auth session timed out before completion |
 | `UZ-AUTH-009` | 403 | Insufficient role | Token role is too low for this endpoint |
 | `UZ-AUTH-010` | 403 | Unsupported role | Token contains an unrecognized role claim |
+| `UZ-AUTH-022` | 403 | Insufficient scope | Token lacks the required `resource:action` scope for this endpoint. The `detail` field names the required scope (e.g. `Requires scope fleet:admin`). |
 
 ## CLI login
 
diff --git a/changelog.mdx b/changelog.mdx
index b29c02a..27693cb 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -22,6 +22,20 @@ export const STAGE_SELF_MANAGED_M66 = "$0.0001";
   agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner.
 </Tip>
 
+<Update label="Jun 30, 2026" tags={["What's new", "API"]}>
+  ## Authorization is now scope-based
+
+  Every capability a token holds is now an explicit `resource:action` scope, read directly off the token — replacing the old `user`/`operator`/`admin` roles and the `platform_admin` flag. A correctly-provisioned principal sees no change: every route that worked before still works, and tenant isolation and workspace ownership are enforced exactly as before. What changes is that "what can this token do?" is now enumerable, and a denial tells you precisely which scope is missing.
+
+  ## API reference
+
+  - **`scopes` claim** — the session token and tenant API key now carry an explicit space-delimited `scopes` list (e.g. `fleet:admin credential:write workspace:admin`). It is provisioned automatically for a workspace owner at signup; a strict client needs no change.
+  - **`403 UZ-AUTH-022` "Insufficient scope"** — a capability denial now names the required scope in the error detail (`Requires scope fleet:admin`), instead of an opaque role rejection.
+  - **`read < write < admin` hierarchy** — per resource, `admin` satisfies `write` satisfies `read`, so a `fleet:admin` holder passes any `fleet:read` route. A destructive route (e.g. `DELETE`) can require the top rung.
+
+  See the [error-codes reference](/api-reference/error-codes) for `UZ-AUTH-022` and the full authorization code registry.
+</Update>
+
 <Update label="Jun 28, 2026" tags={["What's new", "UI", "API", "Bug fixes"]}>
   ## Template installs now explain why a credential is needed