Skip to content

Roles, levels and the authority guard

A role in Facet is a normal document in the iam.Roles doctype. You edit it like any other record. One guard bounds this power. It decides who may change identities and roles, and by how much.

Caller elects one role Caller elects one role

A role bundles permission lines. A line on a parent doctype also covers its child doctypes. The table shows the parts of one line.

Part Holds
action read, create, update, delete, *, or a named action such as promote
on a doctype path, such as production.Project
scope optional named row scopes on the doctype, combined with OR
except optional doctype paths subtracted from the reach

Next to its lines, a role carries visible_tags. A field is visible only when all its tags sit in that list. The role also carries a level from 0 to 100. The level is required, and it orders roles by authority.

Level orders roles. A request runs under exactly one elected role. Roles never merge. The guard reads the level of the elected role, not the highest role the caller holds.

Every caller-controlled write on iam.Account and iam.Roles passes through one guard. It covers document create, update, and delete, named actions, and rollback transitions. It runs after validation. Route-level authorization skips do not bypass it. A refused write answers 403 with details. Only internal system calls bypass it.

Check Rule
Caller level Read from the elected role’s level. A missing or malformed level denies the write.
Account assignment Every role in the final roles array must exist, be live, and sit at or below the caller level. default_role must be a member of roles.
Target protection No write to an account with a higher role ceiling, or to a role with a higher level.
Role authoring The resulting level must not exceed the caller level. Every resulting permission line must be implied by the previous role or the caller’s role. New visible tags must sit inside the union of both.

The containment also covers the other power fields of a role. A write may not push the connectivity channels or the assistant budget past what one baseline role implies. A write that adds an unknown power field is denied.

Same level is enough for assignment. A caller may assign an existing role at its own level, even when that role holds permissions the caller lacks. But a caller cannot create a role above its own level. And a caller cannot widen a role past what the previous role or its own role implies. Those changes need an admin at a higher level.

The trade-off. The guard stops a caller from raising their own authority. The cost is friction. Lowering a high account or widening a role needs an admin at a higher level. Roles also do not nest or inherit. The level orders roles; it does not cascade rights. Each role lists its own permissions in full.