Previewkernable is not released yet: these docs describe work in progress, and things may change before 1.0.Not released yet.Request early access →
Skip to content

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 ​

  1. Inviting. CreateInvitation with 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.
  2. 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; ResendInvitation replaces it with a new one.
  3. The acceptance page. Your API calls peekInvitation(token) to show the tenant's name and whether the invitation expired.
  4. 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.
  5. 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.

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:

CommandWhat it does
CreateInvitationLinka link into groups (never as owner), optionally with a label, an expiry (expiresAt) and a limit (maxUses)
JoinWithInvitationLinkthe signed-in account joins the tenant with the link's groups; sent by your API
RevokeInvitationLinkthe link stops working at once
  • Creating goes through KitApi.createInvitationLink(context, tenant, { groups, label?, expiresAt?, maxUses? }). It generates the token link_<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. ListInvitationLinks lists 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 ​

AggregateUnique keysFacts
invitation.invitationemail—
invitation.link——

Commands ​

Secret fields leave the vault once the command completes; personal fields stay in the vault until their subject is erased.

CommandFieldsWritesWho may send itRefused with
CreateInvitation
on invitation
email: string
groups?: InvitedGroup[]
owner?: boolean
InvitationCreateda group permission; only with permissions the sender holdsexists, invalid_email, invalid_groups; requires: group.group is active
ResendInvitation
on invitation
—InvitationResenta group permissioninvalid_state
RevokeInvitation
on invitation
—InvitationRevokeda group permissioninvalid_state
DeclineInvitation
on invitation
token: string (secret)InvitationDeclinedanyone (the request carries its proof)expired_token, invalid_token
AcceptInvitation
on invitation
token: string (secret)
accountId: string
email: string
newAccount: boolean
InvitationAcceptedthe API (its api group)expired_token, invalid_account, invalid_token, wrong_email
RecordInvitationMailSent
on invitation
tokenId: stringInvitationMailSentonly the kit's reactors—
EraseInvitation
on invitation
—InvitationRevoked, InvitationErasedthe platformnot_found
CreateInvitationLink
on link
secret: string (secret)
groups?: InvitedGroup[]
label?: string
expiresAt?: number | null
maxUses?: number | null
InvitationLinkCreateda group permission; only with permissions the sender holdsexists, invalid_expiry, invalid_groups, invalid_max_uses, invalid_secret; requires: group.group is active
RevokeInvitationLink
on link
—InvitationLinkRevokeda group permissioninvalid_state
JoinWithInvitationLink
on link
token: string (secret)
accountId: string
InvitationLinkUsedthe API (its api group)exists, expired_token, invalid_account, invalid_token, used_up

Events ​

EventFieldsVaultNote
InvitationCreatedemail: string | null
groups: InvitedGroup[]
owner: boolean
tokenId: string
token: string | null
expiresAt: 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.
InvitationResentpreviousTokenId: string
tokenId: string
token: string | null
expiresAt: number
token under token:<tokenId>; erases token:<previousTokenId>A new token; erases the old one.
InvitationRevokedtokenId: stringerases usedToken—
InvitationDeclinedtokenId: stringerases usedToken—
InvitationAcceptedtokenId: string
accountId: string
newAccount: boolean
groups: InvitedGroup[]
owner: boolean
erases usedTokenThe identity reactor creates the identity with these groups (and the owner) from it.
InvitationMailSenttokenId: string——
InvitationErased—erases invitation:<id>Erases the invited email: when the tenant is deleted, or the person asks.
InvitationLinkCreatedgroups: InvitedGroup[]
hash: string
label: string
expiresAt: number | null
maxUses: 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———
InvitationLinkUsedaccountId: string
groups: 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.

QueryFieldsAboutAnswerWho may ask
ListInvitations
by invitation.invitations
——InvitationRow[]a group permission
PeekInvitation
by invitation.invitations
token: string—{ tenant: string; invitationId: string; email: string | null; owner: boolean; expired: boolean }the API (its api group)
ListInvitationLinks
by invitation.invitations
——LinkRow[]a group permission
PeekInvitationLink
by invitation.invitations
token: string—{ tenant: string; linkId: string; label: string; usable: boolean }the API (its api group)

Listeners ​

ListenerOnSubmits
invitation.invitations (read model, order -20)InvitationCreated, InvitationResent, InvitationRevoked, InvitationDeclined, InvitationAccepted, InvitationErased, InvitationLinkCreated, InvitationLinkRevoked, InvitationLinkUsed, TenantDeleted—
invitation.mail (reactor, order -10)InvitationCreatedside effects only
invitation.mail (reactor, order -10)InvitationResentside effects only
invitation.owners (reactor, order -10)TenantCreatedCreateInvitation
invitation.cleanup (reactor, order -25)TenantDeletedEraseInvitation