Skip to main content

Permission Groups

A permission group is a named collection of users that the platform's access control layer can treat as a single subject. Rather than granting capabilities to every user one by one, administrators grant them to a group, and every member of the group inherits the grant. Groups make access policy easier to manage, easier to audit, and easier to change as people join, move between teams, or leave.

What a permission group represents​

A permission group is a tenant-scoped object with a stable identity and a human-readable purpose. It does not, by itself, grant any capability — it is simply a set of users that can be referenced from elsewhere. Capabilities arrive when the group is named in a permission grant or an authorization rule; the group then acts as a convenient handle for "everyone who should have this access".

Typical uses include:

  • Mirroring an organisational team or department so that team-wide access can be granted in one place.
  • Defining a functional role (for example, "Compliance Reviewers") that cuts across the org chart.
  • Carving out a temporary working group for a project or initiative.
  • Grouping external users (such as customer-side approvers) so that a partner organisation can be managed as a unit.

Group attributes​

Each group carries a small set of identifying attributes:

AttributePurpose
NameUnique, human-readable name within the tenant
TypeClassifies the group (e.g. team, role, project, partner)
DescriptionFree-text description of who the group is for and what it is used for
Active flagAllows the group to be enabled or disabled without deletion

Group types are useful for filtering and reporting — for example, separating team groups from project groups in the administration UI — but they have no effect on how membership or grants behave.

As with all Foundation entities, groups are tenant-scoped, audit-tracked, and soft-deactivated rather than permanently deleted, so the historical record of who belonged to which group and when is preserved.

Membership​

A group's membership is made up of zero or more members. Each member is one of two things:

  • A user — an individual tenant user account is added directly to the group.
  • Another group — a group is added as a member of another group, so that every member of the inner group is also treated as a member of the outer group.

This dual style of membership is what makes groups composable. A small, focused group can be reused inside many larger groups without having to maintain duplicate user lists.

Each membership entry has its own lifecycle independent of the group itself:

AttributePurpose
MemberThe user or group being added
Start dateWhen the membership becomes effective
End dateWhen the membership lapses, if known in advance
Active flagAllows the membership to be enabled or disabled independently

A user can belong to as many groups as needed, and a group can appear inside as many other groups as needed.

Nested groups and recursive membership​

Because a group can contain other groups, groups can be nested to any depth. The platform resolves membership recursively: if a user is in group A, and group A is a member of group B, then the user is treated as a member of both A and B for the purposes of access control. If B is itself a member of C, the same user is also a member of C, and so on.

A small example:

In this example, Alice is added directly to the "NZ Compliance Team" group. She is therefore also an effective member of the "Compliance Reviewers" group, and of "All Reviewers", without needing to be listed in either of them by name.

Membership is always resolved through the currently active set of memberships — expired or deactivated memberships are ignored, and cycles between groups are detected and prevented.

The practical effect is that access policy can be expressed once, at the most specific group that is meaningful, and broader grants attached to higher-level groups continue to work as the lower-level groups change.

How groups are used by permissions and authorization​

Permission groups are not themselves a permission system. They are a way of naming a set of users so that the platform's two access control mechanisms can refer to them collectively.

  • Direct permissions can be granted to a group instead of an individual user. Every effective member of the group — including members brought in by nesting — receives the grant. Revoking the grant from the group revokes it from everyone in one step.
  • Authorization (ReBAC) rules can reference groups as subjects when defining who has a relationship to an object. For example, a rule might state that "members of the Compliance Reviewers group can approve this application", and the platform will resolve membership recursively when evaluating the rule.

Because both mechanisms accept groups as subjects, switching a user's group membership immediately changes what they can do, with no need to revisit individual permission grants. This is the main operational benefit of grouping users at all.

Who can create and manage groups​

Group management is a tenant-administrative function:

  • Creating, renaming, or deactivating a group is restricted to users with administrative permission on the tenant's access control area.
  • Editing membership — adding or removing users, or nesting one group inside another — is similarly restricted, although administrators may delegate management of specific groups to other users where appropriate.
  • Viewing groups is more broadly available: many tenant users need to see group names and membership in order to understand who can do what, and the directory and authorization screens surface this information subject to the usual permission checks.

Because granting a group a permission can immediately expand the access of every member, group changes are audit-tracked, and the standard audit fields record who created or last changed each group and each membership entry.