From 15ad0b574f6443193490fdcab35f4849c5cd64f3 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Tue, 30 Jun 2026 00:50:07 +0530 Subject: [PATCH 1/2] =?UTF-8?q?docs(m104):=20changelog=20=E2=80=94=20scope?= =?UTF-8?q?-based=20authorization?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the M104_001 auth-model change for API consumers and operators: the explicit scopes claim, the 403 UZ-AUTH-022 'Insufficient scope' shape, and the read --- changelog.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/changelog.mdx b/changelog.mdx index b29c02a..1ffa27a 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. + + ## 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. + + The full scope catalogue — every scope, what it grants, and the default provisioning grants — is documented in the authorization reference. + + ## Template installs now explain why a credential is needed From a60a3b7292a61810de42fe18894452051a24db19 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Tue, 30 Jun 2026 09:59:14 +0530 Subject: [PATCH 2/2] docs(m104): link authorization ref, add UZ-AUTH-022 to error-codes Greptile PR #114: 'authorization reference' on changelog.mdx:36 was unlinked and no /authorization page exists. Link to the existing error-codes reference instead, reword to match what's there, and add the missing UZ-AUTH-022 row to the error-codes table (referenced in the changelog but absent from the registry page). --- api-reference/error-codes.mdx | 1 + changelog.mdx | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) 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 1ffa27a..27693cb 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -33,7 +33,7 @@ export const STAGE_SELF_MANAGED_M66 = "$0.0001"; - **`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. - The full scope catalogue — every scope, what it grants, and the default provisioning grants — is documented in the authorization reference. + See the [error-codes reference](/api-reference/error-codes) for `UZ-AUTH-022` and the full authorization code registry.