sync_group_members

Purpose

Replaces a group's membership with exactly the supplied user ids.

Every id must already belong to the group's team. A group grants permissions inside one tenant, so an outsider is refused rather than silently skipped — and the whole call fails rather than partly applying, so you never end up with a membership you did not ask for.

Tier

Gated on Growth only when the sync adds somebody. A sync that only removes people succeeds on any tier.

This is the one write in the identity surface whose gate depends on its argument. Deciding from the tool alone would leave a lapsed creator unable to take one person out of a group without deleting the whole group — and deleting is not gated, so the gate would only be pushing them toward the more destructive option. See what the tier gates.

Required ability

group:update — the same ability as update_group.

Input schema

{
  "type": "object",
  "properties": {
    "group_id": {
      "type": "string",
      "description": "UUID of the group whose membership is being replaced."
    },
    "user_ids": {
      "type": "array",
      "description": "Complete list of user UUIDs the group should contain. An empty array clears it."
    }
  },
  "required": ["group_id", "user_ids"]
}

Output shape

{
  "data": {
    "id": "1f68d92a-04c5-4e83-97b1-3d6a05e2f847",
    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "member_ids": [
      "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
      "6f9b2e37-c184-4a05-8d72-30e16bc9f458"
    ]
  }
}

Emits group.members_synced, carrying added_ids and removed_ids as well as the final list — an access-control mirror should not have to diff two snapshots to work out what moved.

A sync that changes nothing emits nothing.

Example prompts

"Put Priya and Sam in the billing group, and nobody else."

"Take Sam out of the billing group."

"Empty the billing group but keep it around."

Failure modes

• AUTHENTICATION_REQUIRED — no authenticated user on the request.
• TOKEN_MISSING_ABILITY — token lacks group:update.
• TEAM_TIER_REQUIRED — the sync adds somebody and the caller's tier does not include Teams. Nothing changes.
• RESOURCE_NOT_FOUND — no such group in any team the caller belongs to.
• VALIDATION_FAILED — one or more ids are not in the group's team. The offending ids are named, and nothing is applied.

Related

• list_groups — read the current membership before replacing it.
• list_team_members — resolve the ids you may use.
• update_group
• Groups API