Skip to main content
A role is a named list of tool permissions: a required allow list and an optional deny list. A profile picks the roles it wants, and every agent on that profile gets exactly that access. Roles are the only way an agent ever gets a tool. Registering a toolset by itself grants nothing. The stacking rule fits in three lines:
An allow entry can also narrow when it applies:
A condition only narrows its own entry, so if another selected role allows tool:workspace:billing.refund outright, the call still goes through. Denies take tools back out, but they only work on built-in tools, never on a toolset namespace. Every new workspace comes with two ordinary roles you can edit or ignore: Administrator (tool:*) and WebOnly (tool:builtin:web.*).
Belongs to a workspace (≤ 64) · Has many allow / deny entries (≤ 32 each) · Selected by profiles (≤ 8 per profile)

​
Rules

  • Allows union, conditions narrow one grant, a deny beats every allow. See Rules.
  • Deleting a role drops it from every profile that selected it.
  • An agent writing a role can only grant what it already holds itself.

​
API

  • Selector grammar, operators, and limits: Permissions.
  • GET/POST /v1/roles, PATCH/DELETE /v1/roles/{roleId}.
  • GET /v1/agents/{agentId}/effective-permissions for what an agent can call right now.