Scoping with groups

Pulse reuses the platform's existing access control. You do not define a separate permission model for agents: you put the agent's user into groups, and grant those groups the right to run specific topologies.

The model #

• A group grants the right to run one or more topologies.
• An agent user (created with its API key) is assigned to one or more groups.
• The agent can run exactly the topologies its groups permit, and nothing else.

This is the same flow you already use for people. A regular user with only a base chat role can do nothing until you add them to a group that can run a topology. An agent works identically.

flowchart LR
  Key["API key (X-Auth)"] --> Agent["Agent user"]
  Agent --> Group["Group"]
  Group --> Topo["Permitted topologies"]

Why this matters #

The manifest and the run path use the same per-user run check. That single gate keeps every group strictly scoped:

• The manifest a caller fetches contains only the topologies its groups can run.
• The run endpoint resolves a tool through the exact same pipeline that built the manifest. A topology outside the caller's scope resolves to an unknown tool and is never executed.

So you can hand different agents different keys, put each key's agent user into a different group, and each agent is confined to its own set of processes, while the underlying system credentials stay shared and centrally managed.

Where to go next #

• API and authentication: create the key and its agent user.
• For your team: the same groups power the Pulse chat.