Skip to content

Roles and permission lines

A role is a document of doctype iam.Roles. Its id is the qualified form iam.Roles.<name>, for example iam.Roles.editor. The role bundles permission lines, a level, field-visibility tags, and the connectivity channels. This page explains the parts and the guard that bounds who may change what.

  • You write or edit a role and must state its reach exactly.
  • You must know why a role write answered 403.
  • You audit which roles hold the sensitive operator actions.
Field Holds
name The unique role name. It forms the document id and is immutable.
level Required integer from 0 to 100. It orders roles by authority.
permissions The permission lines.
visible_tags The field tags the role may see. Default ["default"]; ["*"] sees all.
connectivity The programmatic channels, see below.
description Free text for people.

One line has four parts. Every part is optional except action and on:

Part Holds
action read, create, update, delete, *, or a named action.
on A doctype path, for example crm.Deal, or the wildcard *.*.
scope An array of named row scopes. They combine with OR.
except An array of concrete paths subtracted from the reach.

A line on a parent path also covers nested children. A line on crm.Project also matches crm.Project.Comment. The wildcard *.* matches every doctype in every domain. Seeded admin roles hold it.

The array form is required on every write path. Each entry names a scope declared on the target doctype. The aliases combine with OR: the line reaches rows that match any entry. Omitting scope reaches every row. See Row scopes for the declaration and the aliases.

except shrinks one line. The entries are concrete domain.Doctype paths; no wildcards. An entry prefix-matches like on: an entry on core.DocType also excludes core.DocType.Comment. It is path arithmetic, not a deny system: it never grants anything, and it only affects the line it sits on.

Every example is a full line, with the effect stated.

{"action": "read", "on": "production.Project", "scope": ["$mine", "$global"]}

This line lets a member read the projects they own and the projects with no owner.

{"action": "create", "on": "crm.Deal"}

This line lets a member create a deal anywhere in crm.Deal.

{"action": "update", "on": "*.*", "except": ["core.Domain", "core.DocType"]}

This line lets a member update every document except the two definition surfaces, so the domain and doctype shapes stay read-only for them.

{"action": "read", "on": "fin.Invoice", "scope": ["$mine"]}

This line lets a member read only the invoices they own.

{"action": "read", "on": "hr"}

A path with one segment and a lowercase domain name covers the whole domain. This line lets a member read every doctype in hr.

connectivity is an array from one closed vocabulary: mcp, webhook, api, and assistant. It decides which programmatic doors the role may open at all. An empty list is a browser-only role. Browser sessions and app tokens are never gated by the field.

  • api — the role may hold API keys. See Machine access: API keys.

  • mcp — agents may sign in through the Model Context Protocol (MCP) surface with this role.

  • webhook — the role may author and receive webhooks. See Outbound webhooks.

  • assistant — the role may open the AI (artificial intelligence) assistant. See Governing the assistant.

    Every channel gate reads the role live. A channel you remove applies on the next request.

Besides the four CRUD actions, a line may grant one named action. The action names that gate fixed routes are worth knowing:

Action On Gates
provision_credentials iam.Account Temporary passwords, invite links, credential-state reads.
mfa_disable iam.Account POST /Api/iam/mfa/disable, the administrator recovery.
publish_artifact the target doctype Minting permanent file links on that doctype.
revoke *.* Revoking any file link.
download *.* Downloading any file as an operator.
purge *.* Force-deleting any file, the audited deletion.

Every caller-controlled write on iam.Account and iam.Roles passes one guard. It covers create, update, delete, named actions, and rollback transitions. A refusal answers 403. The caller’s level comes from the one elected role of the request, never from the highest role they hold.

Check Rule
Assignment Every role in the final roles array must exist, be live, and sit at or below the caller’s level. default_role must be a member.
Same level A caller may assign a role at their own level, even when that role holds powers the caller lacks.
Target protection No write to an account or role whose current level is above the caller’s level, not even to lower it.
Role authoring The resulting level must not exceed the caller’s level. Every new line must be implied by the previous role or the caller’s role. New visible tags must sit inside the union of both. The connectivity channels and the assistant budget follow the same containment.

The containment rule bounds a role editor: a level-30 editor cannot widen a level-20 role past what the previous content or their own role implies. See Assigning roles and role election for the assignment flow.

Role id Level Reach
iam.Roles.admin 100 * on *.*, all channels, all tags.
iam.Roles.editor 30 Reads and edits content everywhere; definition surfaces and core.SystemSettings are carved out with except.
iam.Roles.viewer 20 Read everywhere, with the same carve-outs.
iam.Roles.comment_author 20 Author-scoped read, update, and delete on core.Comment through $mine.
iam.Roles.attachment_owner 20 Uploader-scoped read, update, and delete on core.Attachment through $mine.
iam.Roles.anonymous 0 Serves requests with no credential. Its read grants are the public API surface. Delete it, and such requests answer 401.

The core.SystemSettings carve-out is the model to copy: the editor and viewer seeds subtract the path from their blanket lines with except: ["core.SystemSettings"], so runtime settings stay administrator-only. A bespoke role can still be granted the path explicitly.

The document id is iam.Roles.<name>, and account documents reference that id. A rename would desync the id from the name, so the update hook refuses any write that carries name. To rename, create a new role under the new name, move the assignments, and delete the old one. The delete hook refuses while any account still holds the role.

Create a regional read role for the fin domain:

Terminal window
curl -k -X POST -H "Authorization: Bearer $FACET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "regional_reader",
"level": 10,
"visible_tags": ["default"],
"permissions": [
{"action": "read", "on": "fin.Invoice"},
{"action": "read", "on": "hr.Employee", "scope": ["$mine"]}
]
}' \
"https://facet.localhost:3443/Api/iam/Roles"

The new role reads every invoice and lets each member read their own employee record. It holds no channels and no operator actions.

Check the four guard rows above. The most common cause is a new permission line that the caller’s own role does not imply, or a target whose level is above the caller’s.

A write with a string scope answers 422 must be an array

Section titled “A write with a string scope answers 422 must be an array”

The write paths require the array form. Change "scope": "$mine" to "scope": ["$mine"].

The name is immutable. Create the role again under the new name.

A member sees a field you expected to hide

Section titled “A member sees a field you expected to hide”

Check visible_tags on their role — see Field visibility with tags.