Groups
Grant access to a named population instead of one person at a time
Overview
A group is a named population that carries a role. Put people in the group, and the group's role applies to all of them.
A group holds no permissions of its own. It carries a role, and the role holds the permissions. That indirection is the whole point:
- Renaming the group, or changing who is in it, changes who is affected without touching what the access means.
- Changing the role changes what the access means for everyone in the group at once.
- The role stays reusable by another group, or by a direct assignment.
The four preset groups
Every organization is seeded with four groups, one per rung of the project ladder.
| Group | Carries | Who belongs here |
|---|---|---|
| Viewers | Project Viewer | People who read the projects they belong to, including their own runs and files. They cannot run a use case, change one, or open anyone else's run. |
| Operators | Project Operator | The everyday shape. They run what the builders publish, and read their own runs, without being able to edit anything. |
| Builders | Project Builder | People who author and publish use cases, agents and knowledge bases, on top of everything an operator can do. |
| Project Admins | Project Admin | Everything a builder can do, plus project membership, API keys, and every run in the project rather than only their own. |
These exist because every operator was otherwise hand-building the same four populations in every organization before they could assign anything to more than one person.
The presets are deletable. They are a convenience, not an access floor. An organization with no builders should be able to remove the empty Builders group.
The undeletable piece is the single Default role, which nothing here touches. See Roles.
Why there is no preset for the organization tiers
The four presets follow the project ladder, because that ladder is what already decides access: a person is either reading, running, building or administering.
Organization Admin and Organization Owner get no preset group on purpose. Organization-level access is conferred by organization membership, not by a population someone curates, so a group for it would be a second place to grant the same thing.
Using groups
Pick or create the group
Start with a preset if it fits. Create a group when you have a population the ladder does not describe, such as "Finance reviewers" or "External auditors".
Give it a role
A preset already carries one. A group you create needs a role assigned to it, either a seeded role or one you authored.
A preset carries exactly one role, deliberately. A group that arrived holding three would be impossible to reason about when its access is questioned.
Add members
Add people to the group. Their access changes at the next decision, with no cache to wait for.
Check effective permissions
Open Effective permissions for one member and confirm they hold what you expect. A person's access is the union of their Default role, their direct assignments, every group they belong to, and any per-person overrides, minus every deny.
Cross-organization groups
A platform administrator can assign an organization to a group on the Org Groups page in the Admin Portal, and configure auto-join for projects.
This is deliberately not available to org owners. Cross-organization assignment has side effects that reach outside the organization doing it: auto-joiners from sibling organizations land in the master organization.
If you need this, ask a platform administrator.
Good practice
This is the single most useful habit in the model. A role on a group is one change when the population changes. The same role on twelve people is twelve changes, and twelve chances to miss one.
One contractor who needs one use case for one month is a direct assignment. Three people in the same situation is a group.
"Finance reviewers" stays accurate when the role changes. "Can run reports" does not.
If someone is in five groups, nobody can answer what they can do without opening effective permissions. Prefer one group carrying a role that is right for them.
An organization with no viewers is clearer without an empty Viewers group, and removing it takes nothing away.
Troubleshooting
Cause to check first: the group has no role, so it grants nothing. A group with no role is a named population and nothing more.
Also check: the role's grants are wildcards, which narrow what the person may do where they already are rather than establishing access to a new project.
Cause: A deny somewhere else wins. Denies beat allows from every source.
Fix: Open Effective permissions for that person and look for the deny. It may be on another group, on a direct assignment, or a per-person override.
Cause to check: they also hold the same access from another source, most often a direct role assignment or a second group.
Cause: Cross-organization assignment is restricted to platform administrators, because it has effects outside your organization.