Inviting Members
How organization invitations work: who can invite which role, the limits, the email, the invitation link and its states, signing in or up from it, and where to customize each part.
Owners and admins invite people by email to join the active organization with a role. The invitee gets an email with a link to /invitation/<id>, signs in or up there if needed, then accepts or declines. Admins see pending invitations on Settings → Members, where they can resend or cancel them.
Everything goes through the invitations service in @kit/organizations (packages/organizations/src/invitations.ts), called from two pages: apps/web/pages/(app)/settings/members.server.ts (invite, resend, cancel) and apps/web/pages/invitation/[id].server.ts (the link: accept, decline, open). Better Auth's organization plugin creates and accepts invitations; the kit writes every other status change itself, guarded on the invitation still being pending, so a cancel can't overwrite an accept made meanwhile.
Click to expandThe invitation dialog with an example address and role selector.
Who Can Invite, and Which Role
| Action | Needs | Notes |
|---|---|---|
| Invite | invitation: create (owners, admins) | Only a role strictly below one of yours: an owner invites admins and members, an admin invites members. Nobody invites an owner. |
| Resend | invitation: create | The role cap is checked again: an admin demoted since can't resend an admin invitation. |
| Cancel | invitation: cancel (owners, admins) | Any pending invitation of the active organization. |
| See the pending list and the invite button | invitation: create and a role you can grant | Every member sees the Members page and its members table; the invitations section (invitations.getPanel()) is null for the rest, so no invitation id reaches them. |
| Accept, decline | the signed-in user whose verified address the invitation was sent to | Checked by the service on every request, whatever the page shows. |
Permissions are the roles' in packages/rbac/src/rbac.config.ts (see Roles and Permissions). The dialog offers only the roles you can grant (getGrantableRoles); the service enforces the same rule, so a hand-crafted request gets a 403.
Limits
| Limit | Default | Where to change it |
|---|---|---|
| How long a link works | 7 days | INVITATION_EXPIRES_IN_DAYS (1–30) |
| Pending invitations per organization | 50 | MAX_PENDING_INVITATIONS (1–1000); past it: INVITATION_LIMIT_REACHED |
| Invitations one user creates per hour, across all their organizations | 20 | apps/web/config/invitations.config.ts → invitesPerHour; past it: 429 INVITE_RATE_LIMITED with the wait |
| Time before the same invitation can be resent | 5 minutes | apps/web/config/invitations.config.ts → resendCooldownMinutes; within it: 429 RESEND_TOO_SOON |
| Members per organization | none | Seats belong to your billing: add an invitation policy |
Page actions don't go through Better Auth's HTTP rate limits, so these are the limits on invitation emails. The counts live in the database, so they hold across Worker isolates. The env vars are documented in Environment Variables.
One address has at most one pending invitation per organization: inviting it again answers ALREADY_INVITED, and an expired one is replaced by the new invitation.
The Email
The service queues the organizationInvitation email itself, in the inviter's language (kept on the invitation, so a resend uses it too), through the same email queue as the auth emails (Auth Emails). It carries the organization, the inviter, the role, the expiry and the link.
- Text:
apps/web/messages/<locale>/emails.server.json→organizationInvitation(yours; server-only, so it never reaches the browser). - Look: the template is the kit's (
packages/email-templates/src/kit-templates.tsx). To replace it, add your ownorganizationInvitationafter the kit's inapps/web/config/email-templates.server.tsx(EMAIL_TEMPLATES), withdefineEmailTemplate.
When a new invitation's email can't be queued, it's logged (invitation email not queued) and the invitation stays pending, so an admin can resend it. When a resend's email can't be queued, the resend fails and the cooldown is given back, so the admin can retry at once.
The Invitation Link
/invitation/<id> (apps/web/pages/invitation/[id].tsx and [id].server.ts) is public: it works signed in or out. The id is the link's secret, so the page is served private, no-store, and the id never appears in logs (a server error logs /invitation/:id). The page reads the invitation on the server and shows one card per state:
| State | Who sees it | Next step |
|---|---|---|
| Pending | the invited, verified user | Accept or Decline |
| Signed out | anyone not signed in | Sign in or Create account, both returning here |
| Wrong account | someone signed in with another address | Sign out and continue: signs out and opens sign-in, returning here |
| Verify your email | the invited address, not verified yet | Resend link: the verification email brings them back here |
| Already a member | a member of the invitation's organization, whatever the invitation's status | Open the organization (a POST; viewing the link never changes the session) |
| Expired | anyone who isn't a member | Ask the inviter for a new one |
| No longer valid | anyone who isn't a member: unknown or malformed links, and accepted, declined, canceled or replaced invitations | Go home. Every unusable link looks the same, so the link reveals nothing. |
Accepting makes the user a member with the invited role, opens that organization and lands on home with "You joined {organization}"; a double click or a second tab joins once and lands the same way. Declining lands on home with a notice; the invitation leaves the pending list and its link stops working.
The page shows the invited address to whoever holds the link, so the right account can sign in. In personal-only account mode every link shows "No longer valid".
Signing In or Up From the Link
Sign in and Create account carry next=/invitation/<id>, which survives email verification, two-factor (app code or backup code), magic links, email codes and OAuth. Both forms open with the invited address filled in, still editable: the loaders read it from the stored invitation (apps/web/lib/invited-email.server.ts), so the address never travels in a URL. In organizations-only mode a user without an organization reaches the invitation without being sent to onboarding first.
Resending and Canceling
On Settings → Members, each pending row's menu offers only what you're allowed to do:
- Resend: a valid invitation is emailed again with the same link, and its expiry restarts. An expired one is replaced by a new invitation (new link; the old one stops working), which counts toward the hourly limit.
- Cancel: after a confirmation, the link stops working at once. An invitation accepted meanwhile stays accepted.
Business Rules (Policies)
To block an invite, a resend or an accept for your own reasons (a seat limit, an allowed domain), register a policy in apps/web/config/invitation-policies.config.server.ts with defineInvitationPolicy. It runs after the kit's own checks, and its message (a translation key) is shown to the user. See Invitation Policies.
Logs
Every outcome logs one structured entry (invitation.created, invitation.accepted, invitation.declined, invitation.refused with its code, …) with the organization, the acting user, the role and the recipient's domain only: never the invitation id, the link or an address. See Logging.
What to Edit
| To change | Edit | Owner |
|---|---|---|
| Link expiry, pending cap | INVITATION_EXPIRES_IN_DAYS, MAX_PENDING_INVITATIONS | you (env) |
| Hourly cap, resend cooldown | apps/web/config/invitations.config.ts | you |
| Who may invite or cancel | packages/rbac/src/rbac.config.ts | you |
| Your own rules (seats, domains) | apps/web/config/invitation-policies.config.server.ts | you |
| Email text | apps/web/messages/<locale>/emails.server.json | you |
| Role names (dialog, lists, link page, email) | apps/web/messages/<locale>/roles.json, roles.server.json (Role Names) | you |
| Email look | apps/web/config/email-templates.server.tsx | you |
| Page and dialog copy | kit namespace invitations (packages/i18n/src/messages/<locale>/invitations.json) | kit |
| The service and UI | packages/organizations | kit: compose your own UI from @kit/organizations/ui rather than forking it |