Update per-resource permissions claim in agent docs

[Shannon Bradshaw (shannonbradshaw)]

Source changes

• RSDK-14415 — rdk#6413, rdk#6439: Add user_permissions to machine auth config with per-user, per-resource, per-method access control enforcement

Docs changes

• docs/build-apps/use-viam-from-an-agent.md: The page claimed "there is no per-resource permission or approval step" and "A key that can read a camera can also move an arm." This is no longer true as of RDK v1.8.0, which ships user_permissions enforcement in the machine's auth config. Replaced the incorrect claim with a brief description of the user_permissions capability.

How I found these

• Xref lookup: upcoming.yaml tracked rdk-user-permissions-config since 2026-09-09, noting the specific line
• Grep matches: 1 page contained the incorrect claim (use-viam-from-an-agent.md line 149)
• Release gate: rdk#6413 (config parsing) shipped in v1.7.0; rdk#6439 (enforcement) shipped in v1.8.0 (2026-09-14). Both commits confirmed on v1.8.0-release branch.

---

Generated by daily docs change agent

🤖 Generated with Claude Code

https://claude.ai/code/session_0121RBMwxdPQAGLrRHhb8Vmt

---

Generated by Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	0ade5d1
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6aaabc01e4c48d00083b1843
😎 Deploy Preview	https://deploy-preview-5321--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 36 (🔴 down 6 from production) Accessibility: 99 (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)]

Critique: this update may set up a broken agent workflow

(Note: I'm Claude, testing this guidance from the CLI side — which makes me a fairly direct stand-in for the "agent" audience this page is written for.)

I ran the added guidance through the CLI to see if an agent could actually act on it, and found three gaps worth discussing before this merges.

1. The CLI can't write this config. I walked the full viam machines part command tree. config only reads — prints the part's JSON to stdout. There is no update/apply verb anywhere in the CLI for machine config. An agent that reads "you can restrict what each API key or user can do... by adding a user_permissions list to the auth section" and then reaches for the CLI (which is what the rest of this page assumes) will hit a dead end. Applying the change requires the app's config-editor UI or a direct app-API call, neither of which this page mentions.

2. No identifier lookup path either. organizations api-key and machines api-key only support create, not list/get. There's no users/members command in the CLI, and whoami returns only an email. An agent has no CLI-native way to discover an existing API key ID or user identifier to put in a user_permissions entry — it would have to mint a brand-new key just to get an ID.

3. The schema isn't documented anywhere a reader (human or agent) can reach. I grepped the whole viamrobotics/docs repo for user_permissions — the only hit is the sentence this PR adds. There's no reference for valid resource/method strings, the _machine special-case resource, default-entry semantics, or the identifier format. The only source of truth right now is rdk#6413 / rdk#6439 and an internal scope doc, neither public. Worth noting too: rdk#6439 says users are identified by API key ID or e-mail, but this page's wording says "API key ID or app user ID" — those may not be the same thing, and it'd be good to reconcile before either one ships as guidance.

Proposed next step: rather than patch the wording in place, I think this needs a small follow-up scope — a reference doc (probably under build-apps or a new auth/permissions page) that enumerates the actual user_permissions schema (resource strings, method format, default semantics) sourced from the RDK structs, plus a corrected note here that applying the config today goes through the app UI, not the CLI. Flagging for a conversation on sequencing rather than proposing a diff myself, since the schema content needs to come from someone with RDK/app context I don't have.

[Shannon Bradshaw (shannonbradshaw)]

Good catches — pushed 0ade5d1 to address points 1 and 2:

• CLI can't write config: added an explicit note that user_permissions is applied through the Viam app's JSON config editor or the app API, not the CLI.
• "model in one screen" bullet: updated from "a machine checks only that a key is valid" to note that per-resource restrictions exist via user_permissions.
• Identifier types: confirmed against rdk/config/config.go — the three valid types are api-key-id, app-user-id, and default. The wording already matches the code. (The reviewer's note about "email" may come from the auth log fields, which log email alongside app-user-id for diagnostics, but the config identifier is the app user ID, not email.)

On point 3 (schema not documented): agreed that a full reference page is needed. That is a larger task than this PR's scope — it would need to enumerate the resource name format (including _machine for non-resource methods), the fully-qualified gRPC method paths, and the default entry semantics. I've recorded this as a follow-up item in the code-map backlog. This PR's goal is narrower: remove the factually incorrect claim that per-resource permissions don't exist.

---

Generated by Claude Code