Roles & permissions
Overview
A role is a bundle of permissions. Accounts are not given individual permissions but a role — which keeps the granting of access surveyable and makes it auditable.
A permission is always named module.object.action, for example customer.read or platform.user.manage. That pattern lets you read a permission without looking it up: who may do what to which thing.
Permissions add up — there is no forbidding. A permission is either granted or not. One role cannot take anything away from another. Someone who sees too much was given it somewhere, not deprived of it somewhere else.
Core tasks
Create a role. New role asks for a name and optionally a description. The description is not decoration: in six months' time it is the only thing that explains what the role was meant for.
Assign permissions. Pick the role on the left; the permission list appears on the right, grouped by module. A counter shows how many of the available permissions are set. Search permissions… finds a single permission without scrolling; Select all and Deselect all operate on the currently visible selection.
Recognise system roles. Shipped roles are marked System. They come with the standard and are maintained across updates.
Fields in detail
The What it does column answers what changes in the system — not what the field is called. The grey name behind the label is the API field: the same thing runs under that name through automation, import and AI tools.
Creating and editing a role
| Field | Required | Values / format | What it does |
|---|---|---|---|
Name name | yes | text, max. 100 characters | What the role is called. It is assigned to accounts — a name by function ("Accounting") lasts longer than one by person. |
Description description | no | text, max. 255 characters | What the role is meant for. The sentence that makes the right choice easier when assigning. |
Permissions permissionNames | yes | several permissions | What the role may do. Every permission reads area.object.action and stands for exactly one capability. |
Own team only teamScoped | no | yes/no | Narrows every permission of this role to the records of the holder's own teams. Permissions add up: if someone holds the same permission through a role that is not team-bound, they stay cross-team. Records they created themselves and projects they are a member of always stay visible. |
How permissions work
| Rule | What it means |
|---|---|
| Permissions add up | Whoever holds several roles holds the union of their permissions. No permission takes another away — removal happens by omission, not by prohibition. |
| Permissions apply per brand | An assignment can be limited to one brand. Whoever holds a permission only in brand A does not see brand B's data — not in lists and not in search. |
| Viewing and editing are separate | A .view permission opens the view, a .manage or .edit permission allows changes. Two-level visibility (view against view_all) tells your own records from other people's. |
| No permission, no page | Without the permission the menu entry does not appear at all. A user who "cannot find" something usually has a permission problem, not a display problem. |
| Reserved permissions | Some permissions are assignable but have no effect yet — they are marked as reserved so a tick does not suggest security that is not there. |
Delivered roles can be changed; an update does not overwrite your customisation.
Settings & permissions
- Permission
platform.role.manage. Without it the page is unreachable. It is effectively the
highest permission in the system — whoever may edit roles can grant themselves every other permission. Hand it out sparingly.
- New modules bring new permissions. After enabling a module its permissions appear in the list.
They are not set to begin with — a new module never widens anybody's authority automatically.
- Permissions work identically everywhere. The same check applies in the interface, over the
API, in the AI assistant and in automations. There is no route that bypasses the check.
- Brand scope. Where data belongs to a brand, a permission applies in exactly the brands it was
assigned in — not in every brand where somebody happens to have some membership.
FAQ & troubleshooting
Someone sees more than they should. Check the account's role. Because permissions add up, the only remedy is removing them where they were granted.
A change does not take effect immediately. Permissions are loaded at sign-in. Signing out and back in establishes the current state.
I cannot find a permission. Use the search above the list. If it is missing entirely, the owning module is not active.
A system role does not fit our organisation. Create your own role rather than rebuilding the system one. That keeps the standard recognisable and your adjustment yours.