Groups
A group is a named set of people. Groups are the unit access control reasons about when more than one person shares a reason to be granted something.
Ownership
Section titled “Ownership”Every group has exactly one home organization. Other organizations hold a link to the group, which lets them use it but not edit it. Household rosters are resident-owned: site administrators cannot create or edit a household, and adding a household member requires a verified-contact invitation accepted by that person. A receiving organization decides admission for each linked member separately. See Sharing a roster for how links are created.
Fields
Section titled “Fields”| Field | Meaning |
|---|---|
name | Localized display name |
description | Optional localized description |
kind | household, team, department, class, tenant, or other |
shareable | Whether the home organization may offer the group to other organizations |
home_org_id | The owning organization |
Membership
Section titled “Membership”A member of a group is either a member or a manager. Household managers invite by email or phone; the recipient must verify an invited contact and accept before joining. Any member may leave. A sole household manager can nominate an eligible existing member and leave immediately; the nominee must accept before becoming manager. Explicit under-16 classifications are ineligible, while missing age data remains eligible. A pending transfer makes the household read-only for seven days and closes it if no successor accepts.
Photos
Section titled “Photos”A group may have a photo, stored through the shared media pipeline. Photos are deduplicated per organization, normalized to WebP, and removed when the last reference goes.
| Route | Purpose |
|---|---|
GET /orgs/{org_id}/groups | List groups linked into an organization |
POST /orgs/{org_id}/groups | Create a non-household group in that organization |
GET /groups/{id} | Read a group |
PUT /groups/{id} | Update name, description, kind, or shareable |
DELETE /groups/{id} | Soft-delete a group owned by the acting organization |
GET /groups/{id}/members | List admitted members by display name and organization-scoped member reference |
POST /groups/{id}/members | Add a member to a non-household group |
DELETE /groups/{id}/members/{member_ref} | Remove a member from a non-household group |
GET /groups/{id}/links | Where this roster is in use |
PUT /groups/{id}/links/{org_id} | Change how this organization admits members. auto and pinned are refused with 403 when external_group_sharing sets require_admission_approval |
POST /groups/{id}/links/{org_id}/accept | Accept a pending proposal |
DELETE /groups/{id}/links/{org_id} | Revoke a link |
POST /groups/{id}/share-offers | Offer the group to another organization |
POST /group-share-offers/redeem | Redeem an offer. Refused with 403 unless external_group_sharing sets external_orgs: allow, or when the roster exceeds max_members |
GET /groups/{id}/admissions | Admission ledger |
POST /groups/{id}/admissions/{member_ref} | Admit or deny one member without exposing a global user ID. Admitting is refused with 403 when it would exceed external_group_sharing max_members |
GET / POST / DELETE /groups/{id}/image | Group photo |
Resident surface
Section titled “Resident surface”| Route | Purpose |
|---|---|
GET /me/groups | Households I belong to, and where each is used |
POST /me/groups | Create a household implicitly |
GET /me/groups/{id} | One household, with the sites it grants access to |
PUT /me/groups/{id} | Rename a household (managers only) |
DELETE /me/groups/{id} | Delete a household (managers only) |
GET /me/groups/{id}/members | Members of a household I belong to |
DELETE /me/groups/{id}/members/{user_id} | Remove another member (managers only) |
DELETE /me/groups/{id}/links/{integration_id} | Revoke a household’s access to a site |
GET /me/groups/{id}/admissions | View each member’s status in each linked organization (household managers only) |
GET /groups/{group_id}/household-invitations | Pending household invitations (managers) |
POST /groups/{group_id}/household-invitations | Invite by email and/or phone; the recipient must accept |
DELETE /groups/{group_id}/household-invitations/{id} | Cancel a pending household invitation |
POST /groups/{group_id}/household-invitations/{id}/resend | Resend a pending household invitation |
POST /household-invitations/preview | Preview a contact-based household invitation |
POST /household-invitations/redeem | Verify the invited contact and accept the household invitation. Returns { group_id } so the dashboard can open that household |
DELETE /me/groups/{id}/members/me | Leave the household; the final member leaving deletes it |
POST /me/groups/{id}/manager-transfer | Nominate an eligible member and leave immediately |
POST /me/groups/{id}/manager-transfer/accept | Accept a pending manager transfer |
POST /me/groups/{id}/manager-transfer/decline | Decline a pending manager transfer |
POST /me/groups/{id}/proposals | Propose my household to a site. Refused with 403 when the site’s external_group_sharing sets member_proposals: deny, or when the household exceeds max_members |
GET /me/group-proposals | Proposal and admission status |