These abilities manage groups from the Group Memberships extension: seat usage, member rosters, and the invitation lifecycle. They are only registered when the extension is active — on other sites they do not appear at all. For the feature itself, see the site administrator guide and the group admin guide; for the ability catalog, see the Abilities API Overview.
Who Can Run These
Group abilities use a shared permission rule: site administrators (manage_options) can manage any group, and a group admin can manage their own group. The one exception is add-group-member, which is restricted to site staff — see below.
get-group-overview
members-only/get-group-overview returns a summary of a group in one call.
| Parameter | Type | Required | Description |
|---|---|---|---|
group_id | integer | Yes | The group to summarize |
Returns: the group’s name and admin_user_id, the subscription status, seat usage (max_seats, seats_used, seats_available), active_member_count, and pending_invitation_count.
list-group-members
members-only/list-group-members lists a group’s members. Takes a required group_id.
Returns: group_id, a count, and a members array with each member’s user_id, email, display_name, and added_at date.
add-group-member
members-only/add-group-member adds an existing user directly to a group, respecting the available seat count.
Who can run it: site staff only (manage_options), deliberately stricter than the other group abilities. A direct add skips the invitee’s consent and the subscription-status checks that the invitation flow enforces — and letting group admins resolve arbitrary email addresses would reveal which addresses have accounts on the site. Group admins should use invite-group-members instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id / email | integer / string | One required | Identifies the existing user to add |
group_id | integer | Yes | The group to add the user to |
Returns: group_id, user_id, and added. Returns an error if the group is full.
remove-group-member
members-only/remove-group-member removes a user from a group, freeing their seat. This is a destructive operation — the removed user immediately loses the access the group provided.
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id / email | integer / string | One required | Identifies the user to remove |
group_id | integer | Yes | The group to remove the user from |
Returns: group_id, user_id, and removed — which reports whether a membership was actually removed, so calling it for a user who was not in the group is safe and simply returns false.
invite-group-members
members-only/invite-group-members invites one or more email addresses to a group. For each address it creates a pending invitation and sends an invitation email. Results are reported per address, so one bad email doesn’t fail the whole batch.
| Parameter | Type | Required | Description |
|---|---|---|---|
group_id | integer | Yes | The group to invite users to |
emails | array of strings | Yes | One or more email addresses to invite |
Returns: invited_count and failed_count, plus an invited array (each with the email, invitation_id, and whether the email_sent) and a failed array (each with the email and the error message, e.g. an invalid address or no seats remaining).
list-pending-invitations
members-only/list-pending-invitations lists a group’s pending (non-expired) invitations. Takes a required group_id.
Returns: group_id, a count, and an invitations array with each invitation’s id, email, status, expires_at, created_at, and invited_by user ID. Invitation tokens are never included, so the acceptance links cannot be reconstructed from this output.
revoke-invitation
members-only/revoke-invitation revokes a pending invitation so it can no longer be accepted.
Who can run it: site administrators, or the group admin of the group the invitation belongs to.
| Parameter | Type | Required | Description |
|---|---|---|---|
invitation_id | integer | Yes | The invitation to revoke (find IDs via list-pending-invitations) |
Returns: invitation_id and revoked.