Skip to main content

Overview

The invite function is the main server plugin function that adds invitation functionality to your Better Auth instance. It returns a BetterAuthPlugin that registers all invite-related endpoints, hooks, and database schemas.

Import

import { invite } from "better-auth-invite-plugin";

Signature

function invite<O extends InviteOptions>(opts: O): BetterAuthPlugin

Parameters

opts
InviteOptions
required
Configuration options for the invite plugin. See the Options page for complete documentation of all available options.

Returns

BetterAuthPlugin
object
A Better Auth plugin object containing:

Usage

Basic Setup

import { betterAuth } from "better-auth";
import { invite } from "better-auth-invite-plugin";

const auth = betterAuth({
  plugins: [
    invite({
      sendUserInvitation: async (data) => {
        // Send invitation email
        await sendEmail({
          to: data.email,
          subject: "You've been invited!",
          body: `Click here to accept: ${data.url}`,
        });
      },
    }),
  ],
});

With Custom Options

import { betterAuth } from "better-auth";
import { invite } from "better-auth-invite-plugin";

const auth = betterAuth({
  plugins: [
    invite({
      // Email sending
      sendUserInvitation: async (data, request) => {
        await sendEmail({
          to: data.email,
          template: data.newAccount ? "new-user-invite" : "role-upgrade",
          data: {
            role: data.role,
            url: data.url,
            token: data.token,
          },
        });
      },
      
      // Permission checks
      canCreateInvite: async ({ inviterUser, ctx }) => {
        return inviterUser.role === "admin";
      },
      
      // Token configuration
      defaultTokenType: "code",
      invitationTokenExpiresIn: 60 * 60 * 24, // 24 hours
      
      // Cleanup
      cleanupInvitesOnDecision: true,
      cleanupInvitesAfterMaxUses: true,
      
      // Hooks
      inviteHooks: {
        afterCreateInvite: async ({ invitation }) => {
          console.log(`Invite created: ${invitation.id}`);
        },
        afterAcceptInvite: async ({ invitedUser }) => {
          console.log(`User accepted invite: ${invitedUser.id}`);
        },
      },
    }),
  ],
});

With Permission-based Access Control

import { betterAuth } from "better-auth";
import { invite } from "better-auth-invite-plugin";

const auth = betterAuth({
  plugins: [
    invite({
      sendUserInvitation: async (data) => {
        // Send email implementation
      },
      
      // Using permission objects
      canCreateInvite: {
        statement: "user:invite:create",
        permissions: ["admin", "manager"],
      },
      
      canCancelInvite: {
        statement: "user:invite:cancel",
        permissions: ["admin"],
      },
    }),
  ],
});

Source Code Reference

Implementation: src/index.ts:17-36

Build docs developers (and LLMs) love