create_group

Create a permission group on a team. Starts empty; add people with sync_group_members.

Purpose

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.

Required ability

group:create

Input schema

{
  "type": "object",
  "properties": {
    "team_id": {
      "type": "string",
      "description": "UUID of the team the group belongs to."
    },
    "code": {
      "type": "string",
      "description": "Stable identifier, alpha-dash. Unique per team and immutable once created."
    },
    "name": { "type": "string", "description": "Human-readable group name." },
    "permissions": {
      "type": "array",
      "description": "Permission codes (entity:action) the group grants."
    }
  },
  "required": ["team_id", "code", "name"]
}

Output shape

{
  "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.

Example prompts

"Create a billing group that can read subscriptions, then put Priya and Sam in it."

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks group:create.
TEAM_TIER_REQUIRED — the caller's platform tier does not include Teams.
RESOURCE_NOT_FOUND — no such team, or the caller is not a member.
VALIDATION_FAILED — code already used on that team, malformed code, or an unknown permission string.