Agent Access: How Do You Scope an Agent's Permissions Safely?

When scoping an agent's permissions safely, several key considerations must be taken into account. The first step is to implement a sign-in group for the shell, which grants access to the application but does not give every product permission. Backend API app roles are responsible for agent access and knowledge category access, and these should be enforced on every sensitive call.

A single authorization module should serve agent list, chat, browse, and content reads, and the SPA should consume capability endpoints rather than parsing roles from the JWT. Citations and downloads should use the same path rules as chat, and UI hide features should not be considered as boundaries.

The distinction between app access, agent access, and knowledge access is crucial. App access determines whether a person can open the shell, while agent access determines which agents they are allowed to talk to and which knowledge they are allowed to see, download, or ground answers on. Naming conventions like front door, catalog, and corpus can help differentiate these three components.

The SPA consumes capability endpoints, rather than decoding roles in the browser, to maintain a single access payload that avoids duplicates and policy drift.

A clear sign-in group for the shell is essential, and app roles on the backend API should map to capabilities, not screens. Roles that mean "may use agent A" and roles that mean "may manage knowledge category A" should be mapped accordingly, with a break-glass admin role that implies both if necessary. These roles should be enforced on the API, filtering GET /api/agents so the catalog rendered by the UI is honest.

The SPA should render 403 errors if someone tampers with agent IDs, and it should not hide buttons or call it security.

Frontend code should speak capabilities, not JWTs, to avoid duplicating policy and policy drift. If someone can manage a restricted knowledge category, they should usually also have the matching agent. This relationship should be encoded as an explicit implication in one authorization service, rather than relying on tribal knowledge.

Users holding only baseline roles should never see restricted categories in browse, download, or retrieval scope clamps. All chat, browse, and cited blobs should share one entitlement story to avoid security gaps.