Roles

Roles group permissions together. Instead of assigning individual policies to each subject, assign a role and the subject inherits all the role's policies. A subject can have multiple roles. Roles work for any subject: users, services, or AI agents.

How roles work

1. Create a role (e.g., editor)
2. Assign policies to the role (e.g., "can read and write documents")
3. Assign the role to subjects (e.g., Alice gets the editor role)

Now Alice can read and write documents, through the role-based access path.

Examples

Role	Typical policies
viewer	Read-only access to resources
editor	Read + write access
admin	Full access including delete
agent-readonly	Read tools only, no write or delete
agent-restricted	Approved tools only, no destructive actions

Role hierarchy (seniority)

Roles can inherit from one another. Role hierarchy models seniority: the parent (senior) role inherits the permissions of its child (junior) roles, plus its own.

Example: make Developer a child of Manager. A subject with the Manager role now gets Manager's own permissions plus everything Developer grants. A subject with only the Developer role does not get Manager's permissions — inheritance flows up toward the senior role, never down.

Roles flow opposite to groups and resources

This is deliberate. Roles are seniority — the senior (parent) inherits the junior (child). Groups and resources are containment — a child inherits its parent (a member of a sub-group inherits the parent group's grants; a file inherits its folder's access). They point in opposite directions because they model different things: "who outranks whom" versus "what is contained in what."