Invitations
Last updated: 2026-05-20
Invitations are a softer alternative to Add Members: instead of force-adding someone, you create a PENDING membership that the invitee can accept or decline.
Permissions — sending invitations requires
group-invitation:create. Cancelling someone else's pending invitation requiresgroup-invitation:delete. Accepting / declining your own invitation requiresgroup-invitation:update. Members can send invitations only when the group's Allow Member Invites toggle is on; OWNER, ADMIN, and MODERATOR can always send invitations.
Invitation lifecycle
| Status | Meaning |
|---|---|
| PENDING | Sent but not yet acted on |
| ACCEPTED | Invitee accepted; the membership becomes active |
| DECLINED | Invitee declined; the membership row is closed out |
| EXPIRED | Invitation passed its expiry without action |
| CANCELLED | Admin or sender revoked the invitation before action |
A pending invitation is stored as a GroupMembership row with invitationStatus: PENDING. It does not grant access until accepted.
Sending invitations
- Open the group's Members tab (
/groups/:groupId/members). - Click Invite (when available — appears for OWNER, ADMIN, MODERATOR, or for MEMBER if
allowMemberInvitesis on). - For each invitee, provide:
- Entity ID — the user / app / service identifier
- Role — role to assign on acceptance (defaults to
MEMBER) - Message — optional note shown to the invitee
- Click Send Invitations.
The result panel reports successes and per-invitee failures (e.g. invitee already a member, entity not found, composition-mode violation).
Accepting an invitation
When you're invited to a group, a pending membership appears in your My Memberships card on the Groups dashboard, flagged as PENDING.
- Click the pending invitation.
- Click Accept — your membership transitions to
ACCEPTED, you join the group with the role chosen by the inviter, andjoinedAtis set. - Click Decline — your membership transitions to
DECLINEDand you do not gain access.
Cancelling an invitation
Senders and group admins can cancel pending invitations before the invitee responds.
- On the Members tab, switch to the Pending Invitations view (or look for rows with the
PENDINGbadge). - Click the cancel / remove icon next to the invitation.
- Confirm.
The invitation transitions to CANCELLED and the invitee can no longer accept it.
Expiry
An invitation can be created with an expiresAt timestamp. After expiry, accepting it returns an error and the invitation is moved to EXPIRED on the next read.
Approval-required groups
If the group has Require Approval to Join turned on, joins requested by members (rather than admin-issued invitations) follow the same flow with an extra step: the request stays PENDING until an OWNER or ADMIN approves it. Approval sets approvedBy / approvedAt on the membership.
Events
Invitation-related events appear in the group's activity feed under the Members filter:
MEMBER_ADDED— on acceptanceINVITATION_SENTINVITATION_ACCEPTEDINVITATION_DECLINEDINVITATION_CANCELLEDINVITATION_EXPIRED
(The exact event-type strings are emitted by the activity service; the Members filter in the activity tab includes all of them.)