Configuration Reference - Better Auth Invite Plugin

This page provides a comprehensive reference for all configuration options available in the invite plugin.

Core Options

getDate

A function to generate the current date for invite operations.

getDate

() => Date

default:"() => new Date()"

Custom date generator function.

invite({
  getDate: () => new Date()
})

invitationTokenExpiresIn

Number of seconds the invitation token remains valid.

invitationTokenExpiresIn

number

default:"3600"

Token expiration time in seconds (default: 1 hour).

invite({
  invitationTokenExpiresIn: 60 * 60 * 24 // 24 hours
})

inviteCookieMaxAge

Maximum age for the invitation cookie in seconds. This controls how long users have to complete the login flow before activating the token if they are not logged in.

Cookie max age in seconds (default: 10 minutes).

invite({
  inviteCookieMaxAge: 600 // 10 minutes
})

Permission Checks

canCreateInvite

A function or boolean that determines if a user can create an invite. Can also accept a Permissions object for integration with the admin plugin.

canCreateInvite

function | boolean | Permissions

default:"true"

Permission check for creating invites.

invite({
  canCreateInvite: async ({ invitedUser, inviterUser, ctx }) => {
    const canCreate = await hasPermission(ctx, 'create-invite');
    return canCreate;
  }
})

Function parameters:

invitedUser: Object with email? and role properties
inviterUser: The user creating the invite (UserWithRole)
ctx: Generic endpoint context

canAcceptInvite

A function or boolean that runs before a user accepts an invite.

canAcceptInvite

function | boolean | Permissions

default:"true"

Permission check for accepting invites.

invite({
  canAcceptInvite: async ({ invitedUser, newAccount }) => {
    const canAccept = await hasPermission(ctx, 'accept-invite');
    return canAccept;
  }
})

Function parameters:

invitedUser: The user accepting the invite (UserWithRole)
newAccount: Boolean indicating if this is a new account

canCancelInvite

A function or boolean that runs before a user cancels an invite. Note: regardless of this option, only the user who created the invite can cancel it.

canCancelInvite

function | boolean | Permissions

default:"true"

Permission check for canceling invites.

invite({
  canCancelInvite: async ({ inviterUser, invitation, ctx }) => {
    return inviterUser.role === 'admin';
  }
})

Function parameters:

inviterUser: The user who created the invite (UserWithRole)
invitation: The invitation being canceled (InviteTypeWithId)
ctx: Generic endpoint context

canRejectInvite

A function or boolean that runs before a user rejects an invite. Note: regardless of this option, only the invitee (user whose email matches the invite email for private invites) can reject it.

canRejectInvite

function | boolean | Permissions

default:"true"

Permission check for rejecting invites.

invite({
  canRejectInvite: async ({ inviteeUser, invitation, ctx }) => {
    return true;
  }
})

Function parameters:

inviteeUser: The user rejecting the invite (UserWithRole)
invitation: The invitation being rejected (InviteTypeWithId)
ctx: Generic endpoint context

Token Configuration

defaultTokenType

The default token type for invitations.

defaultTokenType

'token' | 'code' | 'custom'

default:"'token'"

token: Generates a 24-character ID using generateId(24)
code: Generates a 6-character alphanumeric code using generateRandomString(6, "0-9", "A-Z")
custom: Uses the generateToken option (required)

invite({
  defaultTokenType: 'code' // ABC123
})

generateToken

A custom function to generate invitation tokens. Required when using defaultTokenType: 'custom'.

generateToken

() => string

Custom token generator function.

invite({
  defaultTokenType: 'custom',
  generateToken: () => {
    return crypto.randomUUID();
  }
})

See Custom Tokens for detailed examples.

Redirect URLs

defaultRedirectToSignUp

The default URL to redirect users to sign up.

Sign-up redirect URL.

invite({
  defaultRedirectToSignUp: '/register'
})

defaultRedirectToSignIn

The default URL to redirect users to sign in.

Sign-in redirect URL.

invite({
  defaultRedirectToSignIn: '/login'
})

defaultRedirectAfterUpgrade

The default redirect URL after upgrading a role or logging in with an invite. Use {token} as a placeholder for the actual token.

defaultRedirectAfterUpgrade

string

Post-upgrade redirect URL with token placeholder.

invite({
  defaultRedirectAfterUpgrade: '/dashboard?invite={token}'
})

defaultCustomInviteUrl

Custom URL format for invite links. Use {token} and {callbackUrl} as placeholders.

defaultCustomInviteUrl

string

Custom invite URL template.

invite({
  defaultCustomInviteUrl: '/join/{token}?callback={callbackUrl}'
})

Default Behavior

defaultShareInviterName

Whether the inviter’s name should be shared with the invitee by default. When enabled, the person receiving the invitation will see the name of the user who created the invitation.

Share inviter name with invitee.

invite({
  defaultShareInviterName: false
})

defaultMaxUses

Maximum times an invite can be used.

defaultMaxUses

number

Maximum number of uses per invite.

invite({
  defaultMaxUses: 10
})

defaultSenderResponse

How the sender should receive the token (only applies when no email is provided).

defaultSenderResponse

'token' | 'url'

default:"'token'"

Response format for invite creator.

invite({
  defaultSenderResponse: 'url'
})

defaultSenderResponseRedirect

Where to redirect the user by default (only if no email is provided).

defaultSenderResponseRedirect

'signUp' | 'signIn'

default:"'signUp'"

Default redirect destination.

invite({
  defaultSenderResponseRedirect: 'signIn'
})

Cleanup Options

cleanupInvitesOnDecision

Delete invitations when a decision is made (rejected, canceled).

cleanupInvitesOnDecision

boolean

default:"false"

Auto-delete invites on rejection or cancellation.

invite({
  cleanupInvitesOnDecision: true
})

cleanupInvitesAfterMaxUses

Delete invitations after they reach maximum uses.

cleanupInvitesAfterMaxUses

boolean

default:"false"

Auto-delete invites after max uses reached.

invite({
  cleanupInvitesAfterMaxUses: true
})

Email Notifications

sendUserInvitation

Send an email to the user with the invite link.

sendUserInvitation

function

Email notification handler for invitations.

invite({
  sendUserInvitation: async (data, request) => {
    const { email, name, role, url, token, newAccount } = data;
    
    await sendEmail({
      to: email,
      subject: `You've been invited to join as ${role}`,
      html: `
        <p>Hi ${name || 'there'},</p>
        <p>You've been invited to join with the role: ${role}</p>
        <p>${newAccount ? 'Create your account' : 'Log in'} here: ${url}</p>
      `
    });
  }
})

Function parameters:

data.email: Recipient email address
data.name: Recipient name (optional)
data.role: Role being assigned
data.url: Full invite URL
data.token: Invite token
data.newAccount: Boolean indicating if this is a new account
request: Request object (optional)

Callbacks

onInvitationUsed

A callback function that is triggered when an invite is used.

onInvitationUsed

function

Callback executed after invite acceptance.

invite({
  onInvitationUsed: async (data, request) => {
    const { invitedUser, newUser, newAccount } = data;
    
    console.log(`User ${newUser.email} accepted invite`);
    console.log(`Role upgraded to: ${newUser.role}`);
    console.log(`New account: ${newAccount}`);
  }
})

Function parameters:

data.invitedUser: Original user before role update (UserWithRole)
data.newUser: User after role update (UserWithRole)
data.newAccount: Boolean indicating if this is a new account
request: Request object (optional)

Hooks

inviteHooks

Hooks for various invite lifecycle events.

inviteHooks

object

Lifecycle hooks for invite operations.

beforeCreateInvite

Runs before a user creates an invite.

invite({
  inviteHooks: {
    beforeCreateInvite: async ({ ctx }) => {
      console.log('Creating invite...');
    }
  }
})

afterCreateInvite

Runs after a user creates an invite.

invite({
  inviteHooks: {
    afterCreateInvite: async ({ ctx, invitation }) => {
      console.log(`Invite created: ${invitation.token}`);
    }
  }
})

beforeAcceptInvite

Runs before a user accepts an invite. You can return a user object to override the invited user.

invite({
  inviteHooks: {
    beforeAcceptInvite: async ({ ctx, invitedUser }) => {
      return {
        user: {
          ...invitedUser,
          name: 'Custom Name'
        }
      };
    }
  }
})

afterAcceptInvite

Runs after a user accepts an invite.

invite({
  inviteHooks: {
    afterAcceptInvite: async ({ ctx, invitation, invitedUser }) => {
      console.log(`User ${invitedUser.email} accepted invite`);
    }
  }
})

beforeCancelInvite

Runs before a user cancels an invite.

invite({
  inviteHooks: {
    beforeCancelInvite: async ({ ctx, invitation }) => {
      console.log(`Canceling invite: ${invitation.token}`);
    }
  }
})

afterCancelInvite

Runs after a user cancels an invite.

invite({
  inviteHooks: {
    afterCancelInvite: async ({ ctx, invitation }) => {
      console.log(`Invite canceled: ${invitation.token}`);
    }
  }
})

beforeRejectInvite

Runs before a user rejects an invite.

invite({
  inviteHooks: {
    beforeRejectInvite: async ({ ctx, invitation }) => {
      console.log(`Rejecting invite: ${invitation.token}`);
    }
  }
})

afterRejectInvite

Runs after a user rejects an invite.

invite({
  inviteHooks: {
    afterRejectInvite: async ({ ctx, invitation }) => {
      console.log(`Invite rejected: ${invitation.token}`);
    }
  }
})

Schema Customization

schema

Custom schema configuration for the invite plugin.

schema

InferOptionSchema<InviteSchema>

Custom database schema configuration.

invite({
  schema: {
    invite: {
      fields: {
        customField: {
          type: 'string',
          required: false
        }
      }
    }
  }
})

See Database Schema for complete schema reference.

Getting Started

Core Concepts

Guides

Advanced

​Core Options

​getDate

​invitationTokenExpiresIn

​inviteCookieMaxAge

​Permission Checks

​canCreateInvite

​canAcceptInvite

​canCancelInvite

​canRejectInvite

​Token Configuration

​defaultTokenType

​generateToken

​Redirect URLs

​defaultRedirectToSignUp

​defaultRedirectToSignIn

​defaultRedirectAfterUpgrade

​defaultCustomInviteUrl

​Default Behavior

​defaultShareInviterName

​defaultMaxUses

​defaultSenderResponse

​defaultSenderResponseRedirect

​Cleanup Options

​cleanupInvitesOnDecision

​cleanupInvitesAfterMaxUses

​Email Notifications

​sendUserInvitation

​Callbacks

​onInvitationUsed

​Hooks

​inviteHooks

​beforeCreateInvite

​afterCreateInvite

​beforeAcceptInvite

​afterAcceptInvite

​beforeCancelInvite

​afterCancelInvite

​beforeRejectInvite

​afterRejectInvite

​Schema Customization

​schema

Build docs developers (and LLMs) love

Core Options

getDate

invitationTokenExpiresIn

inviteCookieMaxAge

Permission Checks

canCreateInvite

canAcceptInvite

canCancelInvite

canRejectInvite

Token Configuration

defaultTokenType

generateToken

Redirect URLs

defaultRedirectToSignUp

defaultRedirectToSignIn

defaultRedirectAfterUpgrade

defaultCustomInviteUrl

Default Behavior

defaultShareInviterName

defaultMaxUses

defaultSenderResponse

defaultSenderResponseRedirect

Cleanup Options

cleanupInvitesOnDecision

cleanupInvitesAfterMaxUses

Email Notifications

sendUserInvitation

Callbacks

onInvitationUsed

Hooks

inviteHooks

beforeCreateInvite

afterCreateInvite

beforeAcceptInvite

afterAcceptInvite

beforeCancelInvite

afterCancelInvite

beforeRejectInvite

afterRejectInvite

Schema Customization

schema