Skip to main content

​
Overview

The Better Auth Invite Plugin adds a comprehensive invitation system to your Better Auth implementation, allowing you to control user sign-ups and manage role upgrades through secure invite codes. This plugin enables you to create, send, and manage invitations for user sign-ups or role changes, giving you fine-grained control over who can access your application and what permissions they receive.

​
Key features

Track invitations

Keep track of who created each invite and who accepted it, providing full audit trails for your user onboarding.

Flexible invite codes

Create invitation codes to control user sign-ups with support for multiple token types (default, code, or custom).

Email integration

Send invitations via email, provide shareable URLs, or generate invitation codes for manual distribution.

Role management

Automatically assign or upgrade roles when invites are used, perfect for team management.

Usage limits

Track each invitation’s usage and enforce maximum uses to prevent abuse.

Secure storage

Store tokens securely in browser cookies for seamless activation during the authentication flow.

​
Additional capabilities

  • Multiple token types: Choose between 24-character tokens, 6-digit codes, or implement custom token generation
  • Cookie-based activation: Tokens are stored securely in cookies and automatically consumed during sign-up or sign-in
  • Customizable behavior: Full control over redirects, token expiration, and email handling
  • Security-focused: Built with security best practices to prevent unauthorized invite usage
  • Welcome pages: Show invitees a custom welcome or role upgrade page after activation

​
Requirements

This plugin requires Better Auth v1.4.13 or newer. Make sure your Better Auth installation meets this requirement before proceeding.
You’ll also need:
  • A Better Auth instance configured with a database adapter
  • Email sending capability (if using private invites sent via email)
  • The admin plugin (recommended for role-based access control)

​
When to use this plugin

The invite plugin is ideal for:
  • Closed beta applications: Control who can sign up during your beta phase
  • Team collaboration: Invite team members and assign roles automatically
  • Role upgrades: Allow users to upgrade from free to paid tiers via invitation
  • Referral systems: Track who invited whom for referral programs
  • Gated communities: Ensure only invited users can create accounts

​
How it works

The invitation system follows a simple flow:
1

Create an invite

An authorized user creates an invitation specifying the target role and optional email address.
2

Send or share

The invite is either sent via email (private) or the token/URL is shared manually (public).
3

Activate the invite

The recipient clicks the invite link or manually activates the token, which stores it in a cookie.
4

Sign up or sign in

When the user signs up or signs in, a hook automatically validates and consumes the invite.
5

Role assignment

The user’s role is set or upgraded according to the invite, and they’re redirected to your welcome page.

​
Architecture overview

​
Database schema

The plugin adds two tables to your database: invite table:
  • token: Unique invitation token
  • createdByUserId: ID of the user who created the invite
  • email: Optional email for private invites
  • role: Role to assign when invite is used
  • maxUses: Maximum number of times this invite can be used
  • expiresAt: Expiration timestamp
  • status: Current status (pending, rejected, canceled, used)
  • shareInviterName: Whether to show inviter’s name to invitee
  • redirectToAfterUpgrade: Optional custom redirect URL
  • newAccount: Whether this is for a new account (private invites only)
inviteUse table:
  • inviteId: Reference to the invite
  • usedByUserId: ID of the user who used the invite
  • usedAt: Timestamp when invite was used

​
Endpoints

The plugin exposes the following API endpoints:
  • POST /invite/create: Create a new invitation
  • POST /invite/activate: Activate an invite token
  • GET /invite/:token: Activate invite via GET (with redirect)
  • GET /invite/get: Get information about an invite
  • POST /invite/cancel: Cancel a pending invite
  • POST /invite/reject: Reject an invite (for invitees)

​
Hooks

The plugin automatically hooks into key authentication endpoints:
  • /sign-up/email
  • /sign-in/email
  • /sign-in/email-otp
  • /verify-email
  • /callback/:id (social logins)
After successful authentication, these hooks check for an invite cookie, validate it, consume it, and upgrade the user’s role.

​
Next steps

Installation

Install the plugin and set up your database schema

Quick start

Get your first invite working in minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us