docs(m104): changelog — scope-based authorization

[indykish]

Changelog entry for M104_001 (agentsfleet PR agentsfleet/agentsfleet#465): authorization is now scope-based — the explicit scopes claim, 403 UZ-AUTH-022, and the read<write<admin hierarchy. Correctly-provisioned principals see no behavior change.

🤖 Generated with Claude Code

Greptile Summary

This PR documents the M104 scope-based authorization change: a new scopes JWT claim, the UZ-AUTH-022 error code for scope denials, and the read < write < admin per-resource hierarchy.

• changelog.mdx — adds a Jun 30 Update entry explaining the behavior change, backward-compatibility guarantee, and what the scopes claim and denial detail look like in practice, with a link to the error-codes reference.
• api-reference/error-codes.mdx — inserts the UZ-AUTH-022 row into the auth table with the correct 403 status and a concrete detail field example.

Confidence Score: 5/5

Safe to merge — both files contain documentation-only additions with no executable logic.

The changes are purely additive documentation: one new table row and one new changelog entry. The error-codes addition is factually consistent with the described API behavior, and the changelog entry correctly links to the reference. No breaking changes to existing content.

No files require special attention beyond the open question about whether UZ-AUTH-009 and UZ-AUTH-010 warrant a deprecation notice alongside the new UZ-AUTH-022 entry.

Important Files Changed

Filename	Overview
changelog.mdx	Adds a well-structured Jun 30 Update entry documenting scope-based auth — scopes claim, UZ-AUTH-022, and the read/write/admin hierarchy. Links correctly to the error-codes reference. The "replacing" language vs. retained UZ-AUTH-009/010 codes could mislead readers about backward compat.
api-reference/error-codes.mdx	Adds UZ-AUTH-022 row in the correct auth section with accurate HTTP status, title, and detail-field description. Insertion point is consistent with surrounding entries.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant API as agentsfleetd
    participant Token as Token Validator

    Client->>API: Request with Bearer token
    API->>Token: Decode token
    Token-->>API: "claims { scopes: "fleet:admin credential:write workspace:admin" }"

    alt Required scope present (e.g. fleet:read satisfied by fleet:admin)
        API-->>Client: 200 OK
    else Required scope missing
        API-->>Client: "403 UZ-AUTH-022 { detail: "Requires scope fleet:admin" }"
    end

    Note over API,Token: read < write < admin hierarchy:
    Note over API,Token: fleet:admin satisfies fleet:write and fleet:read

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client
    participant API as agentsfleetd
    participant Token as Token Validator

    Client->>API: Request with Bearer token
    API->>Token: Decode token
    Token-->>API: "claims { scopes: "fleet:admin credential:write workspace:admin" }"

    alt Required scope present (e.g. fleet:read satisfied by fleet:admin)
        API-->>Client: 200 OK
    else Required scope missing
        API-->>Client: "403 UZ-AUTH-022 { detail: "Requires scope fleet:admin" }"
    end

    Note over API,Token: read < write < admin hierarchy:
    Note over API,Token: fleet:admin satisfies fleet:write and fleet:read

Loading

_{Reviews (2): Last reviewed commit: "docs(m104): link authorization ref, add ..." | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentsfleet	🟢 Ready	View Preview	Jun 29, 2026, 7:21 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.