---
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; the "Deactivate users" dialog reads every page of it for platform and project invites), `GET /preview` and `POST /accept` (**fully public**, the JWT is the security, both rate-limited per IP with `authnRateLimit`), `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.** `countReservedSeats` (`user-invitation.service.ts`) expresses it as SQL (`withinReservationWindow` for `status IN (PENDING, ACCEPTED)` + expiry cutoff, and `EMAIL_IS_NOT_ALREADY_A_PLATFORM_USER`), and `listInvitesReservingSeats` reuses those same pieces; `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.
- **A plan that loses `projectRolesEnabled` keeps its project invites.** They still reserve a seat. `DELETE /:id` lets platform admins and API keys remove them anyway (the trial's seat dialog relies on it, decision 000049), but a project-level admin is refused because the project-permission check requires the flag. Accepting one creates the platform user, then fails with "Project roles are not enabled" before adding the project membership or deleting the invite (known, unfixed, 2026-10-14).
- **Re-inviting a previously deleted user** works only because the CE/EE user delete also removes the now-orphaned `UserIdentity` (see [Users](./users.md)). 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.
- **Opening the link never accepts the invite; the Accept click does.** `/invitation` reads `GET /preview` (platform name, logo, member count, status) and calls `POST /accept` only on the button. Email scanners such as Microsoft Safe Links open every link, so an accept-on-load page let them accept on the invitee's behalf. The cost: an invitee who skips the link and signs up from the login page stays `PENDING`, and `provisionUserInvitation` (which takes only `ACCEPTED`) joins them to nothing.
- **A dead link can mean "revoked" or "already joined", and the page can't tell which.** Provisioning deletes the invitation, so a member who clicks the old email link gets the same 404 as a revoked invitee. The dead-link card says so and offers Sign in, rather than sending members to their admin.

### 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.
