Skip to main content
A permission group is a named set of people that grants can be made to. Grant a group access to a layer, a secret, or a Semantic Layer folder, and everybody in the group has it, including anybody you add later. This is what keeps access control proportional to the number of teams rather than the number of people. Onboard a new analyst by putting them in the Analysts group, and they inherit every grant that group holds, in one call, with no permission API involved.
Managing groups requires an API key created by an Owner or an Admin. A key created by a Member can read groups but not change them. See the ceiling rule.

​
A group grant is live, not a snapshot

This is the property worth building on. A grant made to a group is evaluated through the group’s membership every time, so:
  • Adding somebody to the group gives them everything the group holds, immediately.
  • Removing them takes it all back, immediately.
Neither requires a permission call. You change the membership; the access follows.
A person’s effective access is the union of every grant that reaches them: their own grants plus every group they are in. Groups add access; they never subtract it.

​
Three ways to set membership

They all do the same thing. Pick whichever fits the shape of your script. The difference that matters: users on the group replaces the membership, while the members endpoints adjust it. Sending {"users": [7]} to a group of twelve leaves one person in it.

​
Pending invitees count

Somebody who has been invited but has not accepted can be put in a group straight away, and the group’s grants attach to them at that moment. That is what lets you finish an onboarding script on the day the contract is signed. See Onboarding flow.

​
The All group

Every workspace has one group named All, marked all_group: true, which automatically contains every member. You can grant to it like any other group, but you cannot change it: Use it for access everybody should have. Anything narrower belongs in a group you create.

​
Typical flow

1

Find or create the group

2

Grant the group its access

Once, for the whole team. See Permissions flow.
3

Add people as they arrive

No permission call. The grants from step two reach them the moment they are in.

Permissions flow

Granting to a group, on all three axes.

Onboarding flow

Invite, group, and grant before somebody accepts.

Permission group object

Every field a group returns.

Groups in the app

The same groups, managed by hand.