Skip to content

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

9.6 KB
Raw Blame

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 where countAdditionalSeatsNeeded feeds checkUsersExceededLimit, which takes a pessimistic_write lock on the platform's platform_plan row and counts reserved invites — the seat is reserved at invite creation, concurrent invites can't overshoot usersLimit, and an over-limit invite fast-fails with QUOTA_EXCEEDED. finalizeInvitation then runs after commit, outside the lock (SMTP/JWT work never holds it): if ACCEPTED → immediate accept(); if PENDING + SMTP configured → emails link, else returns link in response.
  • provisionUserInvitation applies 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 on usersLimit.
  • 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 + projectRolesEnabled plan flag; platform invitations require platform ownership.
  • If SMTP unconfigured, the link field is included in the response for the caller to surface manually; if configured, link is 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 is min(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 EXISTS on an existing platform user); wouldAddNewUser re-checks the same membership condition in TypeScript; countAdditionalSeatsNeeded restates 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, with EXISTING_USER.
  • POST /accept answers with registered — true when an identity already claims the invited email. The web accept page routes on exactly that field: falsy sends the recipient to /sign-up, true to /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 with EXISTING_USER.
  • A platform invite can carry one project. The PLATFORM row reuses the projectId and projectRoleId columns that used to be empty for platform invites, so it is still one row and one email. On accept, provisionUserInvitation sets the platform role, then adds the membership through addToInvitedProject; it runs after the default projects join, so the picked role wins over Editor. If the plan lost projectRolesEnabled before 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. claimInvitedProject settles 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. loadProvisioningContext filters both by platformId (built-in roles have none), and addToInvitedProject skips 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-invitations keeps 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/users returns hasProjects (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 on POST /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. createInvitationRecord now finds the PLATFORM row by email and platform and updates it, removing any older duplicates, and the route holds a distributedLock per platform and email so two concurrent invites can't both insert. Because a PLATFORM row can now carry a projectId, 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) stays ACCEPTED when 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. provisionUserInvitation only 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 (with resent) 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 entity
  • packages/core/shared/src/lib/management/invitations/index.ts — UserInvitation, InvitationType, InvitationStatus, and the request contracts
  • packages/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 links
  • packages/web/src/features/members/api/ — frontend API client
  • packages/web/src/features/members/hooks/ — TanStack Query hooks

Paths verified 2026-07-26.