> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matrices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles

> Named bundles of tool access.

A role is a named list of tool permissions: a required `allow` list and an
optional `deny` list. A [profile](/model/profiles) 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](/model/toolsets) by
itself grants nothing.

The stacking rule fits in three lines:

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
effective tools = union(allows) − union(denies)
any matching deny, in any selected role  → denied
no selected roles                        → nothing
```

An `allow` entry can also narrow *when* it applies:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "tool": "tool:workspace:billing.refund",
  "where": [{ "path": "input.region", "op": "eq", "value": "eu" }]
}
```

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.*`).

<Info>
  **Belongs to** a workspace (≤ 64) · **Has many** allow / deny entries (≤ 32
  each) · **Selected by** profiles (≤ 8 per profile)
</Info>

## Rules

* Allows union, conditions narrow one grant, a deny beats every allow. See
  [Rules](/model/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](/reference/permissions).
* `GET`/`POST /v1/roles`, `PATCH`/`DELETE /v1/roles/{roleId}`.
* `GET /v1/agents/{agentId}/effective-permissions` for what an agent can call
  right now.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.