Appearance
Invitations
An invitation brings a person into a tenant by email: with some groups, or as an owner. It works for people who already have an account and for people who do not, and it is the only way in when the platform's sign-up policy keeps registration closed. An invitation link lets many people in through one link instead.
One aggregate, invitation.invitation, with a random ID, under the tenant it invites to. It is open until it is accepted, declined or revoked; it expires after INVITATION_DAYS (7), which is computed, not an event. Each tenant holds at most one open invitation per email.
The flow
- Inviting.
CreateInvitationwith the email and the groups (each optionally scoped to one aggregate). The inviter may only hand out groups they could grant themselves (no escalation). Owner invitations (owner: true) are for owners and the platform. - The mail. The reactor sends a token of the form
<tenantId>.<invitationId>.<tokenId>.<secret>, so the token alone tells your API which tenant to accept it in. The token waits in the vault until it is used;ResendInvitationreplaces it with a new one. - The acceptance page. Your API calls
peekInvitation(token)to show the tenant's name and whether the invitation expired. - Accepting, through
KitApi.acceptInvitation(token, as):- Signed in: the account's email must be the invited one (else
wrong_email). - New person: they choose a name and password; the account is registered at once and is active, since the token proved the email. Someone whose email already has an account must sign in first (
sign_in_first), so nobody ends up with an account they cannot use.
- Signed in: the account's email must be the invited one (else
- Afterwards, the identity reactor creates the person's identity in the tenant (or keeps the one they have), grants the invitation's groups, and adds them as owner for an owner invitation.
The invited person may also decline (DeclineInvitation with the token). The tenant's admins may revoke an open invitation.
Invitation links
An invitation link lets people in without an invitation per email: Ann puts a link on her shop's website, and whoever opens it, signs in and joins gets the link's groups. It is a second aggregate, invitation.link:
| Command | What it does |
|---|---|
CreateInvitationLink | a link into groups (never as owner), optionally with a label, an expiry (expiresAt) and a limit (maxUses) |
JoinWithInvitationLink | the signed-in account joins the tenant with the link's groups; sent by your API |
RevokeInvitationLink | the link stops working at once |
- Creating goes through
KitApi.createInvitationLink(context, tenant, { groups, label?, expiresAt?, maxUses? }). It generates the tokenlink_<tenantId>.<linkId>.<secret>and returns it once; only its hash is stored, as for API keys. The creator may only hand out groups they could grant themselves (no escalation). - Joining goes through
KitApi.joinWithInvitationLink(claims, token). The person must be signed in: unlike an emailed invitation, a link proves no email address, so someone new registers and verifies first, then joins. Each account joins through a link once; a link that expired, is used up or was revoked is refused (expired_token,used_up,invalid_token). - Afterwards the identity reactor creates the person's identity in the tenant (or keeps theirs) with the link's groups, exactly as for an accepted invitation. Every join is an event (
InvitationLinkUsed), so the audit shows who came in through which link. peekInvitationLink(token)gives the join page what it shows: the tenant, the link's label and whether it can still be used.ListInvitationLinkslists a tenant's links with how often each was used.
Tenants created by the platform
When the platform creates a tenant for someone (CreateTenant with owner: { email }), the kit sends that person an owner invitation. Accepting it makes them the tenant's first owner.
Personal data
An invitation keeps its email after it is closed, so the audit shows who was invited and when. EraseInvitation removes it, when the person asks or when the tenant is deleted (a reactor does that for every invitation of the tenant).
Reference
Types
The types the tables below name, from invitation/domain.ts:
ts
type InvitationStatus = "none" | "open" | "accepted" | "declined" | "revoked";
interface InvitedGroup { group: string; scope?: { type: string; id: string } | null }
type LinkStatus = "none" | "open" | "revoked";Aggregates
| Aggregate | Unique keys | Facts |
|---|---|---|
invitation.invitation | email | — |
invitation.link | — | — |
Commands
Secret fields leave the vault once the command completes; personal fields stay in the vault until their subject is erased.
| Command | Fields | Writes | Who may send it | Refused with |
|---|---|---|---|---|
CreateInvitationon invitation | email: stringgroups?: InvitedGroup[]owner?: boolean | InvitationCreated | a group permission; only with permissions the sender holds | exists, invalid_email, invalid_groups; requires: group.group is active |
ResendInvitationon invitation | — | InvitationResent | a group permission | invalid_state |
RevokeInvitationon invitation | — | InvitationRevoked | a group permission | invalid_state |
DeclineInvitationon invitation | token: string (secret) | InvitationDeclined | anyone (the request carries its proof) | expired_token, invalid_token |
AcceptInvitationon invitation | token: string (secret)accountId: stringemail: stringnewAccount: boolean | InvitationAccepted | the API (its api group) | expired_token, invalid_account, invalid_token, wrong_email |
RecordInvitationMailSenton invitation | tokenId: string | InvitationMailSent | only the kit's reactors | — |
EraseInvitationon invitation | — | InvitationRevoked, InvitationErased | the platform | not_found |
CreateInvitationLinkon link | secret: string (secret)groups?: InvitedGroup[]label?: stringexpiresAt?: number | nullmaxUses?: number | null | InvitationLinkCreated | a group permission; only with permissions the sender holds | exists, invalid_expiry, invalid_groups, invalid_max_uses, invalid_secret; requires: group.group is active |
RevokeInvitationLinkon link | — | InvitationLinkRevoked | a group permission | invalid_state |
JoinWithInvitationLinkon link | token: string (secret)accountId: string | InvitationLinkUsed | the API (its api group) | exists, expired_token, invalid_account, invalid_token, used_up |
Events
| Event | Fields | Vault | Note |
|---|---|---|---|
InvitationCreated | email: string | nullgroups: InvitedGroup[]owner: booleantokenId: stringtoken: string | nullexpiresAt: number | email under invitation:<id>; token under token:<tokenId> | The email belongs to the invitation (its own subject); the token sits in the vault until used. |
InvitationResent | previousTokenId: stringtokenId: stringtoken: string | nullexpiresAt: number | token under token:<tokenId>; erases token:<previousTokenId> | A new token; erases the old one. |
InvitationRevoked | tokenId: string | erases usedToken | — |
InvitationDeclined | tokenId: string | erases usedToken | — |
InvitationAccepted | tokenId: stringaccountId: stringnewAccount: booleangroups: InvitedGroup[]owner: boolean | erases usedToken | The identity reactor creates the identity with these groups (and the owner) from it. |
InvitationMailSent | tokenId: string | — | — |
InvitationErased | — | erases invitation:<id> | Erases the invited email: when the tenant is deleted, or the person asks. |
InvitationLinkCreated | groups: InvitedGroup[]hash: stringlabel: stringexpiresAt: number | nullmaxUses: number | null | — | A reusable invitation: anyone signed in who has its token may join the tenant with these groups, until it is revoked, expires or is used up. Only the token's hash is kept: the API shows the token once. |
InvitationLinkRevoked | — | — | — |
InvitationLinkUsed | accountId: stringgroups: InvitedGroup[] | — | Someone joined through the link: the identity reactor creates their identity with these groups. |
Queries
A query about one aggregate names it (static target): the middleware decides on that aggregate as on a command's.
| Query | Fields | About | Answer | Who may ask |
|---|---|---|---|---|
ListInvitationsby invitation.invitations | — | — | InvitationRow[] | a group permission |
PeekInvitationby invitation.invitations | token: string | — | { tenant: string; invitationId: string; email: string | null; owner: boolean; expired: boolean } | the API (its api group) |
ListInvitationLinksby invitation.invitations | — | — | LinkRow[] | a group permission |
PeekInvitationLinkby invitation.invitations | token: string | — | { tenant: string; linkId: string; label: string; usable: boolean } | the API (its api group) |
Listeners
| Listener | On | Submits |
|---|---|---|
invitation.invitations (read model, order -20) | InvitationCreated, InvitationResent, InvitationRevoked, InvitationDeclined, InvitationAccepted, InvitationErased, InvitationLinkCreated, InvitationLinkRevoked, InvitationLinkUsed, TenantDeleted | — |
invitation.mail (reactor, order -10) | InvitationCreated | side effects only |
invitation.mail (reactor, order -10) | InvitationResent | side effects only |
invitation.owners (reactor, order -10) | TenantCreated | CreateInvitation |
invitation.cleanup (reactor, order -25) | TenantDeleted | EraseInvitation |
