People, roles and permissions
People, roles and permissions
A permission is one named right, such as costs:read or tasks:write. People get permissions through roles, which bundle them, or directly; what you may do is everything your roles and direct grants add up to.
Permissions
Every module names its own permissions after itself: projects:read, projects:write, projects:manage. Most modules have a few tiers, from seeing, to changing, to managing. Each module page lists its permissions in a table under "Who can do what".
A screen or an action asks for one or more permissions. You need every one it asks for. A sidebar entry asks for one too, and you do not see the entry without it.
The core owns a few permissions of its own, for the things no module owns:
| Permission | What it lets you do |
|---|---|
audit:read | View the audit trail |
users:read | View users |
users:manage | Create and edit users, and clear sign-in locks |
roles:manage | Manage roles and permissions: create roles, give and take them, grant permissions directly |
modules:manage | Install and disable modules (a platform administrator's right; see Workspaces and modules) |
themes:manage | Upload and disable themes, which every viewer of the deployment then loads |
api-keys:manage | Mint and revoke API keys |
secrets:read | See which named secrets exist, never their values |
secrets:manage | Enter, replace and remove named secrets. People only: an API key or an agent holding it is still refused |
entitlements:manage | Grant and revoke which modules a workspace may use |
tenant:manage | Change workspace-wide settings, such as the organisation's theme and colours |
sso:manage | Federate this deployment with others for single sign-on |
notifications:read | See where alerts are sent |
notifications:manage | Change where alerts are sent |
notifications:inbox | Let a tool, such as an agent or an API key, read and clear your own notifications |
Your own appearance, profile, password and inbox need no permission at all.
Roles
A role is a named list of permissions, such as "Editor". Everyone holding the role gets every permission on it.
A role can also include other roles. "Administrator includes Editor includes Viewer" means Editor carries everything Viewer has plus its own, and Administrator carries both. Change Viewer once and every role above it changes too. Cycles are refused.
On Admin → People → Roles, each role shows:
- Includes: the roles it takes in, directly and further down the chain;
- Inherited: permissions that arrive only through an included role;
- Carried by this role itself: its own list;
- Effective: everything together, which is what actually decides a request.
How it adds up for a person
What you may do is the union of:
- the permissions you were granted directly ("Direct grants" on the People tab), and
- the effective permissions of every role you hold.
Permissions only add up. Nothing subtracts one. To take something away, take away the role or the direct grant that gives it.
The permission picker offers only the permissions of modules that are switched on, plus the core's.
Administrators
A person marked Administrator passes every permission check in their own workspace. Their grants list is often empty, which does not mean they hold nothing.
An administrator is not a reader of everyone's content, though. Most modules narrow rows to the people they belong to, and that narrowing applies to administrators too, except where a module says otherwise (Projects shows administrators every project, for example). See Sharing and visibility. An administrator's rights never reach another workspace.
Rules that keep access safe
- You can only give what you hold. Nobody can grant a permission, or a role carrying one, that they do not hold themselves. The same goes for API keys and agents: a key or an agent is never stronger than the person who made it.
- Nothing becomes ungrantable by accident. Removing a person, a role, a grant or an API key is refused if it would leave nobody in the workspace able to grant some permission. The screen names what would be lost and asks you to accept it before going ahead (accepting needs
roles:manage). - Every change is recorded. The Audit trail tab shows what changed and who changed it, for every request that changes something.
Where to manage it
- Admin → People: who is here, their roles and direct grants, the roles themselves, the audit trail and sign-in locks. Seeing it needs
iam:read. The People module also declaresiam:manage, but every change to roles and grants is checked against the core'sroles:manage. See People. - Account → API keys: what a key may do. See API keys and MCP access.
- Agents → Agents → Modules: which modules an agent may use. See Agents and approvals.