Skip to main content

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 requires group-invitation:delete. Accepting / declining your own invitation requires group-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​

StatusMeaning
PENDINGSent but not yet acted on
ACCEPTEDInvitee accepted; the membership becomes active
DECLINEDInvitee declined; the membership row is closed out
EXPIREDInvitation passed its expiry without action
CANCELLEDAdmin 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​

  1. Open the group's Members tab (/groups/:groupId/members).
  2. Click Invite (when available — appears for OWNER, ADMIN, MODERATOR, or for MEMBER if allowMemberInvites is on).
  3. 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
  1. 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.

  1. Click the pending invitation.
  2. Click Accept — your membership transitions to ACCEPTED, you join the group with the role chosen by the inviter, and joinedAt is set.
  3. Click Decline — your membership transitions to DECLINED and you do not gain access.

Cancelling an invitation​

Senders and group admins can cancel pending invitations before the invitee responds.

  1. On the Members tab, switch to the Pending Invitations view (or look for rows with the PENDING badge).
  2. Click the cancel / remove icon next to the invitation.
  3. 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 acceptance
  • INVITATION_SENT
  • INVITATION_ACCEPTED
  • INVITATION_DECLINED
  • INVITATION_CANCELLED
  • INVITATION_EXPIRED

(The exact event-type strings are emitted by the activity service; the Members filter in the activity tab includes all of them.)


See also​