[DRAFT] DOCS-4936: Draft fine-grained permissions documentation (hold until Member ships)

[Jeremy Rose (jeremyrose-viam)]

Do not merge until the Member role is selectable in the Viam app. This PR is held as a whole: merging publishes the new page and the Member description on docs/organization/rbac.md, which document behavior that isn't active yet.

This adds a page on fine-grained permissions and describes the Member role on the role-based access control page.

What the new page covers (docs/organization/fine-grained-permissions.md)

• Who a policy applies to. Owners and operators have machine-wide permission and are never limited. A member can call only what a grant allows, on the resources the grant names.
• How viam-server evaluates a call, as a table. It covers unauthenticated callers, duplicate entries, a caller's own entry, no entry, calls that act on the machine as a whole (_machine), and unknown subject types, plus the PermissionDenied error, the log warning and the closed streams.
• How to define an access policy in a machine's configuration (access_policy), with a field table.
• How to define the same rules in a local configuration file (auth.user_permissions, with auth.handlers and the default entry), for a standalone viam-server v1.8.0 or later.

What the RBAC page gets: a Member bullet, a sentence that an access policy never limits owners or operators, and a goals-table row linking to the new page. The permission tables get no Member columns, because a member's permissions are whatever its grants say.

Verification status. Written from source and tickets, not tested end-to-end, because access policies aren't active yet on any machine I could test.

• Evaluation rules and local-config format: read from RDK v1.10.0 (robot/web/authorization.go, config/config.go).
• access_policy fields and validation: read from the app's data/access_policy.go.
• Member and owner/operator semantics, and the baseline method set: from the description of viamrobotics/app#13423, which wasn't merged when this was drafted.
• Each unverified point is an HTML comment tagged TODO(verify, DOCS-4936) in the files. They include the baseline methods, fragment grants, whether resource names are checked at save, _machine UX, app-user-id entries in local config, and the no-wildcard claim for user_permissions.

Timing: engineering is rolling this out, and this PR is ready to merge once these ship: viamrobotics/app#13426 (activation and feature flag, APP-17821), viamrobotics/app#13423 (compiler, APP-17820) and viamrobotics/app#13484 (policy editor UI, APP-17822). The UI steps will follow that last one.

Also in this branch: the agent-page correction from #5428, so merging that first leaves no conflict. This branch adds the Member and access_policy wording to that page, which describes behavior that isn't active yet.

Refs DOCS-4936, APP-17623.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	d5d832c
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6ad18659888c88a518c95838
😎 Deploy Preview	https://deploy-preview-5429--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 40 (🟢 up 5 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 60 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.