App Invite

The App Invite plugin enables you to invite users to your application through email invitations. It supports two types of invitations:

• Personal Invitations: Targeted to specific email addresses, ensuring only the intended recipient can use the invitation
• Public Invitations: Can be used by multiple users, making it ideal for open sign-up scenarios

This plugin is particularly useful for invite-only applications.

Installation

npm install @better-auth-extended/app-invite

import { betterAuth } from "better-auth";
import { appInvite } from "@better-auth-extended/app-invite";

export const auth = betterAuth({
    // ... other config options
    plugins: [
        appInvite({
            // required for personal invites
            sendInvitationEmail: (data) => {
                // ... send invitation to the user
            },
        }),
    ],
});

import { createAuthClient } from "better-auth/client";
import { appInviteClient } from "@better-auth-extended/app-invite/client";

const authClient = createAuthClient({
    plugins: [appInviteClient()],
});

npx @better-auth/cli migrate

npx @better-auth/cli generate

Usage

To add members to the application, we first need to send an invitation to the user. The user will receive an email with the invitation link. Once the user accepts the invitation, they will be signed up to the application.

Setup Invitation Email

For personal invites to work we first need to provide sendInvitationEmail to the better-auth instance. This function is responsible for sending the invitation email to the user.

You'll need to construct and send the invitation link to the user. The link should include the invitation ID, which will be used with the acceptInvitation function when the user clicks on it.

This is only required for personal invites. Sharing public invitations is up to the inviter.

import { betterAuth } from "better-auth";
import { appInvite } from "@better-auth-extended/app-invite";
import { sendAppInvitation } from "./email";

export const auth = betterAuth({
    plugins: [
        appInvite({
            async sendInvitationEmail(data) {
                const inviteLink = `https://example.com/accept-invitation/${data.id}`;
                sendAppInvitation({
                    name: data.name,
                    email: data.email,
                    invitedByUsername: data.inviter.name,
                    invitedByEmail: data.inviter.email,
                    inviteLink,
                });
            },
        }),
    ],
});

Send Invitation

To invite users to the app, you can use the invite function provided by the server and client.

const { data, error } = await authClient.inviteUser({    email,    resend,    domainWhitelist,});

const data = await auth.api.inviteUser({    body: {        email,        resend,        domainWhitelist,    },});

Accept Invitation

When a user receives an invitation email, they can click on the invitation link to accept the invitation. The link should include the invitation ID, which will be used to accept the invitation.

const { data, error } = await authClient.acceptInvitation({    invitationId, // required    name,    email,    password, // required});

const data = await auth.api.acceptAppInvitation({    body: {        invitationId, // required        name,        email,        password, // required    },});

Update Invitation Status

To update the status of invitations you can use the acceptInvitation, rejectInvitation, cancelInvitation function provided by the client. The functions take the invitation id as an argument.

const { data, error } = await authClient.cancelInvitation({    invitationId, // required});

const data = await auth.api.cancelAppInvitation({    body: {        invitationId, // required    },});

const { data, error } = await authClient.rejectInvitation({    invitationId, // required});

const data = await auth.api.rejectAppInvitation({    body: {        invitationId, // required    },});

Get Invitation

To get an invitation you can use the getAppInvitation function provided by the client. You need to provide the invitation id as a query parameter.

const { data, error } = await authClient.getAppInvitation({    id, // required});

const data = await auth.api.getAppInvitation({    query: {        id, // required    },});

List Invitations

Allows a user to list all invitations issued by themselves. By default 100 invitations are returned.

const { data, error } = await authClient.listInvitations({    searchField,    searchValue,    searchOperator,    limit,    offset,    sortBy,    sortDirection,    filterField,    filterValue,    filterOperator,});

const data = await auth.api.listAppInvitation({    query: {        searchField,        searchValue,        searchOperator,        limit,        offset,        sortBy,        sortDirection,        filterField,        filterValue,        filterOperator,    },});

Schema

The plugin requires an additional table in the database.

Table Name: appInvitation

Options

canCreateInvitation: ((ctx: GenericEndpointContext) => Promise<boolean> | boolean | Promise<Permission> | Permission) | boolean | Permission - A function that determines whether a user can create an invitation. By default, it's true. You can set it to false to restrict users from creating invitations.

canCancelInvitation ((ctx: GenericEndpointContext, invite: AppInvitation) => Promise<boolean> | boolean | Promise<Permission> | Permission) | boolean | Permission - A function that determines whether a user can cancel invitations. By default, the user can only cancel invites they created. You can set it to false to restrict users from canceling invitations.

canCancelInvitation: {
    statement: "appInvite",
    permissions: ["create"],
};

sendInvitationEmail: async (data) => Promise<void> - A function that sends an invitation email to the user. This is only required for personal invitations.

invitationExpiresIn: number - How long the invitation link is valid for in seconds. By default an invitation expires after 48 hours (2 days). Set it to null to prevent invitations from expiring.

autoSignIn: boolean - A boolean value that determines whether to prevent automatic sign-up when accepting an invitation. Defaults to false.

cleanupExpiredInvitations: boolean - Clean up expired invitations when a value is fetched. Default true.

cleanupPersonalInvitesOnDecision: boolean - Cleanup personal invitations when a decision is made. Default false.

verifyEmailOnAccept: boolean - Whether to verify email addresses when accepting invitations. Default true.

resendExistingInvite: boolean - Whether to resend existing invitations, instead of creating a new one. Default false.

hooks.create.before: (ctx: GenericEndpointContext) => Promise<void> | void - A function that runs before an invitation is created.

hooks.create.after: (ctx: GenericEndpointContext, invitation: AppInvitation) => Promise<void> | void - A function that runs after an invitation was created.

hooks.accept.before: (ctx: GenericEndpointContext, userToCreate: Partial<User> & { email: string }) => Promise<{ user?: User; } | void> | { user?: User; } | void; - A function that runs before an invitation is accepted.

hooks.accept.after: (ctx: GenericEndpointContext, data: { invitation: AppInvitation; user: User; }) => Promise<void> | void - A function that runs after an invitation was accepted.

hooks.reject.before: (ctx: GenericEndpointContext, invitation: AppInvitation) => Promise<void> | void - A function that runs before an invitation is rejected.

hooks.reject.after: (ctx: GenericEndpointContext, invitation: AppInvitation) => Promise<void> | void - A function that runs after an invitation was rejected.

hooks.cancel.before: (ctx: GenericEndpointContext, invitation: AppInvitation) => Promise<void> | void - A function that runs before an invitation is canceled.

hooks.cancel.after: (ctx: GenericEndpointContext, invitation: AppInvitation) => Promise<void> | void - A function that runs after an invitation was canceled.

schema: The schema for the app-invite plugin. Allows you to infer additional fields for the user and appInvitation tables. This option is available in the client plugin as well.

allowUserToCreateInvitation: boolean | ((user: User, type: "personal" | "public") => Promise<boolean> | boolean) - A function that determines whether a user can invite others. By defaults it's true. You can set it to false to restrict users from creating invitations. (deprecated. use canCreateInvitation instead.)

allowUserToCancelInvitation: (data: { user: User, invitation: AppInvitation }) => Promise<boolean> | boolean - A function that determines whether a user can cancel invitations. By default the user can only cancel invites created by them. You can set it to false to restrict users from canceling invitations. (deprecated. use canCancelInvitation instead.)