create_group
Create a permission group on a team. Starts empty; add people with sync_group_members.
Creates a group: a named permission bundle several collaborators in a team can share. Someone can be in more than one.
The distinction from a role is what each attaches to. A role is what one collaborator is — everyone holds exactly one. A group is a bundle a set of people share. Both carry permissions. Neither bundles projects.
A group starts empty. Add people with sync_group_members — membership is deliberately not a field here, because naming a group and deciding who it applies to are different operations with different consequences.
Choose the code deliberately
code is unique within the team and cannot be changed afterwards —
permissions are addressed by it. Only name and the permission set stay
mutable.
Growth-tier capability. On a lower tier this returns TEAM_TIER_REQUIRED and
creates nothing.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it. It reaches beyond Subscriby: a connector, a provider or a member.
Arguments
team_id*stringUUID of the team the group belongs to.
code*stringStable identifier, alpha-dash. Unique per team and immutable once created.
name*stringHuman-readable group name.
permissionsarrayoptionalPermission codes (entity:action) the group grants.
What it returns
{ "data": { "id": "1f68d92a-04c5-4e83-97b1-3d6a05e2f847", "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86", "code": "billing-team", "name": "Billing Team", "permissions": ["project-subscription:view-any"] }}Emits group.created.
How it fails
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks group:create.
TEAM_TIER_REQUIREDthe caller's platform tier does not include Teams.
RESOURCE_NOT_FOUNDno such team, or the caller is not a member.
VALIDATION_FAILEDcode already used on that team, malformed code, or an unknown permission string.
How is this guide?
Last updated on