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.

The invitation dialog with an example address and role selector.Click to expand

The invitation dialog with an example address and role selector.

Who Can Invite, and Which Role

ActionNeedsNotes
Inviteinvitation: 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.
Resendinvitation: createThe role cap is checked again: an admin demoted since can't resend an admin invitation.
Cancelinvitation: cancel (owners, admins)Any pending invitation of the active organization.
See the pending list and the invite buttoninvitation: create and a role you can grantEvery 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, declinethe signed-in user whose verified address the invitation was sent toChecked 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

LimitDefaultWhere to change it
How long a link works7 daysINVITATION_EXPIRES_IN_DAYS (1–30)
Pending invitations per organization50MAX_PENDING_INVITATIONS (1–1000); past it: INVITATION_LIMIT_REACHED
Invitations one user creates per hour, across all their organizations20apps/web/config/invitations.config.ts → invitesPerHour; past it: 429 INVITE_RATE_LIMITED with the wait
Time before the same invitation can be resent5 minutesapps/web/config/invitations.config.ts → resendCooldownMinutes; within it: 429 RESEND_TOO_SOON
Members per organizationnoneSeats 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 own organizationInvitation after the kit's in apps/web/config/email-templates.server.tsx (EMAIL_TEMPLATES), with defineEmailTemplate.

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.

/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:

StateWho sees itNext step
Pendingthe invited, verified userAccept or Decline
Signed outanyone not signed inSign in or Create account, both returning here
Wrong accountsomeone signed in with another addressSign out and continue: signs out and opens sign-in, returning here
Verify your emailthe invited address, not verified yetResend link: the verification email brings them back here
Already a membera member of the invitation's organization, whatever the invitation's statusOpen the organization (a POST; viewing the link never changes the session)
Expiredanyone who isn't a memberAsk the inviter for a new one
No longer validanyone who isn't a member: unknown or malformed links, and accepted, declined, canceled or replaced invitationsGo 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".

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 changeEditOwner
Link expiry, pending capINVITATION_EXPIRES_IN_DAYS, MAX_PENDING_INVITATIONSyou (env)
Hourly cap, resend cooldownapps/web/config/invitations.config.tsyou
Who may invite or cancelpackages/rbac/src/rbac.config.tsyou
Your own rules (seats, domains)apps/web/config/invitation-policies.config.server.tsyou
Email textapps/web/messages/<locale>/emails.server.jsonyou
Role names (dialog, lists, link page, email)apps/web/messages/<locale>/roles.json, roles.server.json (Role Names)you
Email lookapps/web/config/email-templates.server.tsxyou
Page and dialog copykit namespace invitations (packages/i18n/src/messages/<locale>/invitations.json)kit
The service and UIpackages/organizationskit: compose your own UI from @kit/organizations/ui rather than forking it