From 2397fb3f657a75698b98aa1561bcb24c9c871717 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 16 Sep 2026 09:07:49 +0000 Subject: [PATCH 1/3] Update per-resource permissions claim in agent docs RDK v1.8.0 ships user_permissions enforcement (rdk#6413, rdk#6439). The claim that "there is no per-resource permission or approval step" is no longer accurate. Replace it with a brief description of the user_permissions config capability. Co-Authored-By: Claude Opus 4.6 (1M context) Claude-Session: https://claude.ai/code/session_0121RBMwxdPQAGLrRHhb8Vmt --- docs/build-apps/use-viam-from-an-agent.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/build-apps/use-viam-from-an-agent.md b/docs/build-apps/use-viam-from-an-agent.md index d91e76348b..4fb5c2d39c 100644 --- a/docs/build-apps/use-viam-from-an-agent.md +++ b/docs/build-apps/use-viam-from-an-agent.md @@ -143,10 +143,13 @@ Read cameras from 300 mm or more above an object. Closer than that, the gripper' - **Converges configuration.** When you add a component or service, the machine applies it within about ten seconds; `GetMachineStatus` reports the revision it reached and each resource's state. -Two things the heartbeat does not cover today: motion-service moves continue after the client that started them disappears, and there is no per-resource permission or approval step. -A key that can read a camera can also move an arm. +One thing the heartbeat does not cover today: motion-service moves continue after the client that started them disappears. Use `StopAll` when a move must end, and give an agent a machine-scoped key rather than a location or organization key when it only needs one machine. +You can restrict what each API key or user can do on a machine by adding a `user_permissions` list to the `auth` section of the machine's JSON config. +Each entry names a user (by API key ID or app user ID) and lists the gRPC methods it may call on specific resources. +Users without a matching entry are fully restricted unless a `default` entry exists. + ## Remembering across sessions Machines, parts, locations, and organizations each carry a metadata document you can read and write through the app API: a place for notes such as calibration offsets or what worked last time. From 0ade5d153d300a426454a659763bdef2d890d551 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 16 Sep 2026 15:55:35 +0000 Subject: [PATCH 2/3] Address review: clarify user_permissions config path and scope - Fix the "model in one screen" bullet to note per-resource restrictions exist (was: "a machine checks only that a key is valid") - Note that user_permissions is applied through the Viam app JSON editor or app API, not the CLI (CLI has no config-write command) - Tighten wording to avoid implying the feature is CLI-driven Co-Authored-By: Claude Opus 4.6 (1M context) Claude-Session: https://claude.ai/code/session_0121RBMwxdPQAGLrRHhb8Vmt --- docs/build-apps/use-viam-from-an-agent.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/build-apps/use-viam-from-an-agent.md b/docs/build-apps/use-viam-from-an-agent.md index 4fb5c2d39c..de9796208b 100644 --- a/docs/build-apps/use-viam-from-an-agent.md +++ b/docs/build-apps/use-viam-from-an-agent.md @@ -26,7 +26,7 @@ If you already have a key and a terminal, the shortest path is [Drive a machine The motion service plans against it. - A **key** authenticates you. Keys are scoped to a machine, a location, or an organization. - Today every key minted from the CLI has full write access to its scope, and a machine checks only that a key is valid, not what it may do. + By default every key has full write access to its scope. Machines can optionally enforce per-resource, per-method restrictions through `user_permissions` in the machine's JSON config (see below). ## Ways in @@ -146,9 +146,10 @@ Read cameras from 300 mm or more above an object. Closer than that, the gripper' One thing the heartbeat does not cover today: motion-service moves continue after the client that started them disappears. Use `StopAll` when a move must end, and give an agent a machine-scoped key rather than a location or organization key when it only needs one machine. -You can restrict what each API key or user can do on a machine by adding a `user_permissions` list to the `auth` section of the machine's JSON config. -Each entry names a user (by API key ID or app user ID) and lists the gRPC methods it may call on specific resources. +Machines support per-resource, per-method access control through a `user_permissions` list in the `auth` section of the machine's JSON config. +Each entry identifies a user by API key ID or app user ID and lists the gRPC methods that user may call on named resources. Users without a matching entry are fully restricted unless a `default` entry exists. +Apply `user_permissions` through the machine's **JSON** config editor in the Viam app or the app API; the CLI does not have a command to write machine config. ## Remembering across sessions From 20c7a4d9611bc07342d4bea22af65128402be965 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 17 Sep 2026 16:59:50 +0000 Subject: [PATCH 3/3] Reframe user_permissions as troubleshooting for agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopt reviewer's suggested framing: an agent encountering a permission error should read the config, report the raw identifiers to a human operator, and escalate — it cannot resolve identifiers, add entries, or write the config itself. Co-Authored-By: Claude Opus 4.6 (1M context) Claude-Session: https://claude.ai/code/session_0121RBMwxdPQAGLrRHhb8Vmt --- docs/build-apps/use-viam-from-an-agent.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/build-apps/use-viam-from-an-agent.md b/docs/build-apps/use-viam-from-an-agent.md index de9796208b..108ddf7d39 100644 --- a/docs/build-apps/use-viam-from-an-agent.md +++ b/docs/build-apps/use-viam-from-an-agent.md @@ -146,10 +146,11 @@ Read cameras from 300 mm or more above an object. Closer than that, the gripper' One thing the heartbeat does not cover today: motion-service moves continue after the client that started them disappears. Use `StopAll` when a move must end, and give an agent a machine-scoped key rather than a location or organization key when it only needs one machine. -Machines support per-resource, per-method access control through a `user_permissions` list in the `auth` section of the machine's JSON config. -Each entry identifies a user by API key ID or app user ID and lists the gRPC methods that user may call on named resources. -Users without a matching entry are fully restricted unless a `default` entry exists. -Apply `user_permissions` through the machine's **JSON** config editor in the Viam app or the app API; the CLI does not have a command to write machine config. +Machines can restrict what an API key or user is allowed to do through a `user_permissions` list in the `auth` section of the machine's JSON config. +This is configured by the machine owner, not something you can set up yourself. +Users without a matching entry are fully restricted unless a `default` entry exists, so a permission error on a key that is otherwise valid may mean it is not listed. +If you hit this, read the machine's config to see the current `user_permissions` entries and report what you find (the resources, methods, and the raw `api-key-id` or `app-user-id` values you see) to your human operator, who can adjust it through the Viam app's JSON config editor or the app API. +You have no way to resolve those identifiers to a person, add a new entry, or change the config yourself. ## Remembering across sessions