AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
icon: ✉️
User Invitations
Lets platform owners (and project members with WRITE_INVITATION) invite users to a platform (granting a PlatformRole) or a specific project (granting a named ProjectRole). New invites are either auto-accepted or kept PENDING with an emailed JWT link the recipient clicks to accept without a login session. On acceptance, platform role or project membership is provisioned, then the invitation is deleted. Pending invitations reserve seats: an invite that would add a new platform user consumes a seat at creation time, so usedSeats = active users + distinct reserved (non-expired) invites (decision 000014).
Entity
user_invitation: platformId, type (PLATFORM/PROJECT), platformRole (nullable), email (lowercased/trimmed), projectId (nullable), status (PENDING/ACCEPTED), projectRoleId (nullable FK). Unique index on (email, platformId, projectId) prevents duplicates. CASCADE relations to project + project_role.
How it works
- Endpoints under
/v1/user-invitations:POST /(create/upsert, USER+SERVICE),GET /(list),POST /accept(fully public — JWT is the security),DELETE /:id(revoke). - Create is split in two. When the invite would add a new platform user (
wouldAddNewUser),createInvitationRecord(one PLATFORM row per email and platform, one PROJECT row per email and project) runs inside a transaction wherecountAdditionalSeatsNeededfeedscheckUsersExceededLimit, which takes apessimistic_writelock on the platform'splatform_planrow and counts reserved invites — the seat is reserved at invite creation, concurrent invites can't overshootusersLimit, and an over-limit invite fast-fails withQUOTA_EXCEEDED.finalizeInvitationthen runs after commit, outside the lock (SMTP/JWT work never holds it): if ACCEPTED → immediateaccept(); if PENDING + SMTP configured → emails link, else returns link in response. provisionUserInvitationapplies all ACCEPTED invites for an email (platform role update or ProjectMember upsert), deleting each after. It performs no seat check — accepting is seat-neutral (reserved invite −1, active user +1) and never blocks onusersLimit.- Invitation link: JWT-signed URL (7-day default) to
<platform-domain>/invitation?token=...&email=....
Gotchas
- Auto-accept: SERVICE-key callers always auto-accept; project invites for already-registered users also auto-accept (added immediately, no click).
- Project invitations require
projectMustBeTeamType+WRITE_INVITATION+projectRolesEnabledplan flag; platform invitations require platform ownership. - If SMTP unconfigured, the
linkfield is included in the response for the caller to surface manually; if configured,linkis omitted and email is sent. Auto-accept + SMTP sends a "project member added" notification instead. - Seat enforcement only bites when billing is enforced for the platform (
isBillingEnforced, OBSERVE otherwise) and is skipped in CE; the seat limit applied ismin(usersLimit, scheduledUsersLimit). Only invites whose email is not yet a platform member reserve a seat, and a repeat invite to the same reserved email needs no extra seat. - The "does this invite reserve a seat" rule has three implementations — change them together.
countReservedInvites(platform-plan.service.ts) expresses it as raw SQL (status IN (PENDING, ACCEPTED)+ expiry cutoff +NOT EXISTSon an existing platform user);wouldAddNewUserre-checks the same membership condition in TypeScript;countAdditionalSeatsNeededrestates the same predicate in a third query builder. Editing one alone makes the counter and the guard disagree, which silently over- or under-counts seats. - Re-inviting a previously deleted user works only because the CE/EE user delete also removes the now-orphaned
UserIdentity(see Users). The invitation itself always succeeds; when that cleanup has not run, the recipient's sign-up is what fails, withEXISTING_USER. POST /acceptanswers withregistered—truewhen an identity already claims the invited email. The web accept page routes on exactly that field: falsy sends the recipient to/sign-up,trueto/sign-in. The route has to spread it onto the invitation explicitly; while it was missing, every invitee landed on/sign-up, where an already-registered email dead-ends withEXISTING_USER.- A platform invite can carry one project. The PLATFORM row reuses the
projectIdandprojectRoleIdcolumns that used to be empty for platform invites, so it is still one row and one email. On accept,provisionUserInvitationsets the platform role, then adds the membership throughaddToInvitedProject; it runs after the default projects join, so the picked role wins over Editor. If the plan lostprojectRolesEnabledbefore they accept, the project is skipped instead of failing the sign-in. - A platform invite and a project invite for the same email and project never overwrite each other. They share the unique index on
(email, platformId, projectId), so a plain upsert used to turn one into the other.claimInvitedProjectsettles it first: a project invite takes the project off the platform invite, and a platform invite deletes a pending project invite for that project, or drops its own project if an accepted project invite already covers it. - Accepting reads the invited project and role scoped to the invite's platform.
loadProvisioningContextfilters both byplatformId(built-in roles have none), andaddToInvitedProjectskips a project or refuses a role that belongs to another platform. - The web requires that project only when personal projects are off; the API never does. For a Member on a plan with project roles, the invite dialog's Project field is optional while personal projects are on (they start in their personal project) and required while they are off, with a line saying why. With personal projects off and no team project at all, the dialog shows "Create a project first" with a Create project button and disables Invite, so nobody is invited into nowhere and nobody is stuck at an empty list.
POST /v1/user-invitationskeeps both fields optional on purpose: API callers (onboarding scripts, embedding customers) often send a platform invite and then a project invite as two calls, and requiring the field would quietly break that automation. The no-projects screen catches anyone a script leaves without a project. - Changing an Admin or Operator to Member asks for a project only when they have none.
GET /v1/usersreturnshasProjects(one batched query,projectService.listUserIdsWithProjects), and the Update User Role dialog makes two calls: a project invite first (accepted automatically, since they're already on the platform), then the role change. Project access stays on the project-member resource, not onPOST /v1/users/:id, and the order means a failure part-way leaves an Admin who is also in a project, never a Member with no project. - Re-inviting an email at platform level updates its existing invite. The unique index
(email, platformId, projectId)never matches a PLATFORM row without a project (NULL is never equal), so an upsert alone inserted a duplicate each time.createInvitationRecordnow finds the PLATFORM row by email and platform and updates it, removing any older duplicates, and the route holds adistributedLockper platform and email so two concurrent invites can't both insert. Because a PLATFORM row can now carry aprojectId, it shares that index key with a PROJECT invite to the same project: a platform invite naming project X deletes the pending project invite to X, and a project invite to X takes X off the platform invite, so neither silently overwrites the other's type. An invite someone already accepted (they clicked the link but haven't signed up yet) staysACCEPTEDwhen it's re-sent, and an accepted project invite is never deleted; if it covers the project, the platform invite simply doesn't take that project.provisionUserInvitationonly deletes an invite if it is unchanged since it read it, so a re-send that lands mid-acceptance isn't lost. - Re-sending an invite someone already accepted keeps it accepted, and still sends them a way in. Accepted means they clicked the link, so it stays accepted to keep sign-up open for them. When they have no account yet,
finalizeInvitation(withresent) treats it as a normal invite: a fresh link (a newly signed token for the same invite, valid 7 days) when SMTP isn't configured, or the invitation email again. API-key invites, which are accepted on the first send, keep their old behaviour. The dialog only calls someone "added" when they're already on the platform.
Key files
Entry point: userInvitationsService, defined in user-invitation.service.ts and called from the routes in user-invitation.module.ts (which exports invitationModule).
packages/server/api/src/app/user-invitations/— the whole backend slice: module + routes, service lifecycle (create, accept, list, delete, provision), TypeORM entitypackages/core/shared/src/lib/management/invitations/index.ts—UserInvitation,InvitationType,InvitationStatus, and the request contractspackages/server/api/src/app/ee/platform/platform-plan/platform-plan.service.ts—checkUsersExceededLimit+countUsedSeats(the seat-reservation counter)packages/web/src/features/members/components/— invite dialog, invitation card with revoke, accept flow for incoming linkspackages/web/src/features/members/api/— frontend API clientpackages/web/src/features/members/hooks/— TanStack Query hooks
Paths verified 2026-07-26.