DOCS-1588: Document per-machine user_permissions authorization

[Shannon Bradshaw (shannonbradshaw)]

Source changes

• RSDK-14415 — RSDK-14415 Support user_permissions in proto and JSON configs rdk#6413: user_permissions in the auth section of the machine JSON and proto config (config.AuthConfig, UserPermission, User, Permission).
• RSDK-14415 — RSDK-14415 Authorize user invocations based on user_permissions rdk#6439: viam-server enforces it with gRPC unary and stream interceptors (robot/web/authorization.go), and revokes streams and video tracks when a reconfigure removes access.
• RSDK-14414 — RSDK-14414 Add UserPermission list to AuthConfig api#885: the UserPermission proto messages.

Released in RDK v1.8.0 (git tag --contains 6fa27780d). The app parses the auth field with RDK's AuthConfigToProto (domains/robotservice/config_retriever.go, app on RDK v1.10.0), so the field reaches cloud-managed machines.

Documents: DOCS-1588 ("Document 'Fine grained robot authorization'").

Docs changes

• docs/organization/access.md: new "Restrict API calls on a machine" section under "Limit access". It covers where the list goes, a JSON example (one API key limited to GetImages on cam1, plus a default entry), a field table, and the rules viam-server applies. The rules: unrestricted when the list is empty; once any entry exists, a caller gets its own entry, else default, else nothing. Unauthenticated connections are fully restricted. A user listed twice is fully restricted. An unknown type is ignored. Denials return PermissionDenied and log unauthorized request. Lost access closes open streams, video included. Module-to-viam-server calls aren't checked, because the module parent server has no such interceptor. A caution notes that Viam app pages such as CONTROL connect as your user (app_user_id auth claim), so restricting default can break them for you.
• docs/organization/rbac.md: one sentence linking to the new section from the role-combinations intro.

The only earlier mention is the agent-facing note in docs/build-apps/use-viam-from-an-agent.md (#5321), which is left as is.

Verification

• The example JSON unmarshals into config.AuthConfig (checked with a Go test against RDK main). Method names match viam.robot.v1.RobotService/GetMachineStatus and viam.component.camera.v1.CameraService/GetImages in the protos.
• The user_id lookup points at ListOrganizationMembers, whose OrganizationMember.user_id is the same AppUser.ID the app puts in the app_user_id claim. GetUserIDByEmail is Viam-staff only, so it isn't suggested.
• prettier 3.2.5 (repo-local), markdownlint, vale 3.12.0 and make build-prod all pass.

How I found these

• Backlog item api-bf81506-user-permission-auth-config (DOCS-1588). Its old gate, "until an SDK exposes the fields", didn't fit: this is machine config, not an SDK method.
• Grep for user_permissions, tls_auth_entities, external_auth_config, "per-resource" and "fine-grained": no existing reference for the machine auth section; one mention on the agent page.

---

Generated by daily docs change agent

🤖 Generated with Claude Code

https://claude.ai/code/session_013FG6a8yrTei5qqd5MRfhYu

---

Generated by Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	c1fc776
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6ac21bfa4b6cad0008d41905
😎 Deploy Preview	https://deploy-preview-5389--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 41 (🟢 up 2 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.

[Jeremy Rose (jeremyrose-viam)]

I couldn't follow the new section on a cloud-managed machine. Saving auth.user_permissions in the machine's JSON config is rejected with: "auth.user_permissions is generated from access_policy at render and cannot be set in config; it appears in rendered configs, so remove it and edit access_policy instead" (requestID 3892951fc5000058fa95a5eb45ae3db4).

The app has its own access_policy section that it compiles into user_permissions. I couldn't get it to take effect on my test machine: the config saved, but the machine never reconfigured and calls weren't denied. It looks unreleased or flagged (the org invite page still offers only Owner and Operator).

Suggest holding this page, or reframing it for standalone viam-server with a local config file only, until access_policy ships. Can you confirm which audience this should serve?

[Jeremy Rose (jeremyrose-viam)]

^^ Please see above comment. ^^

[Jeremy Rose (jeremyrose-viam)]

Closing this in favor of #5429, which documents this feature for both cloud-managed machines and local config files.

The reason: on a machine managed in the Viam app, saving auth.user_permissions in the JSON config is rejected, because the app generates it from a top-level access_policy section. The steps in this PR (CONFIGURE → JSON → add auth.user_permissions → Save) fail at the save. The new PR documents access_policy for cloud-managed machines and keeps user_permissions for standalone viam-server with a local config file. It's a draft and on hold until the Member role is selectable in the app.

Carried over from here: the config example, the field table, the rules viam-server applies, and the link from the role-based access control page. The rules table now also covers unauthenticated callers and unknown subject types.

Not carried over yet: the CONTROL-tab caution, the claim that module calls aren't checked, and how to find user and API key IDs. They're tracked as TODOs in the draft.

Thank you for the source references in this PR. They saved a lot of time.