Skip to main content

​
Overview

The inviteClient function is the client-side plugin that enables invite functionality in your Better Auth client. It provides type-safe methods for creating, activating, canceling, and managing invitations from your frontend application.

​
Import

import { inviteClient } from "better-auth-invite-plugin/client";

​
Signature

function inviteClient(): BetterAuthClientPlugin

​
Returns

​
BetterAuthClientPlugin
object
A Better Auth client plugin object containing:

​
Setup

​
Client Configuration

import { createAuthClient } from "better-auth/client";
import { inviteClient } from "better-auth-invite-plugin/client";

const authClient = createAuthClient({
  baseURL: "http://localhost:3000",
  plugins: [inviteClient()],
});

export default authClient;

​
Available Methods

Once the client plugin is configured, the following methods are available on your auth client:

​
createInvite

Create a new invitation. 
const result = await authClient.invite.createInvite({
  email: "[email protected]",
  role: "member",
  tokenType: "code",
  maxUses: 1,
});
Parameters:
  • email (string, optional): Email address for private invite
  • role (string, required): Role to assign to the invited user
  • tokenType (“token” | “code” | “custom”, optional): Type of token to generate
  • redirectToSignUp (string, optional): Custom sign-up redirect URL
  • redirectToSignIn (string, optional): Custom sign-in redirect URL
  • maxUses (number, optional): Maximum number of times invite can be used
  • expiresIn (number, optional): Seconds until token expires
  • redirectToAfterUpgrade (string, optional): Redirect URL after role upgrade
  • shareInviterName (boolean, optional): Share inviter’s name with invitee
  • senderResponse (“token” | “url”, optional): How to return the token (public invites only)
  • senderResponseRedirect (“signUp” | “signIn”, optional): Where to redirect (public invites only)
  • customInviteUrl (string, optional): Custom invitation URL pattern
Returns: 
{
  status: boolean;
  message: string; // Contains token/URL for public invites, or confirmation for private invites
}

​
activateInvite

Activate an invitation token. 
const result = await authClient.invite.activateInvite({
  token: "invite-token-here",
  callbackURL: "/dashboard",
});
Parameters:
  • token (string, required): The invitation token to activate
  • callbackURL (string, optional): Where to redirect after activation
Returns: 
{
  status: boolean;
  message: string;
  action?: "SIGN_IN_UP_REQUIRED";
  redirectTo?: string;
}

​
getInvite

Get details about an invitation. 
const result = await authClient.invite.getInvite({
  token: "invite-token-here",
});
Parameters:
  • token (string, required): The invitation token to look up
Returns: 
{
  status: boolean;
  inviter: {
    email: string;
    name: string | null;
    image: string | null;
  };
  invitation: {
    email: string | null;
    createdAt: Date;
    role: string;
    newAccount: boolean;
  };
}

​
cancelInvite

Cancel a pending invitation (only the creator can cancel). 
const result = await authClient.invite.cancelInvite({
  token: "invite-token-here",
});
Parameters:
  • token (string, required): The invitation token to cancel
Returns: 
{
  status: boolean;
  message: string;
}

​
rejectInvite

Reject a private invitation (only the invitee can reject). 
const result = await authClient.invite.rejectInvite({
  token: "invite-token-here",
});
Parameters:
  • token (string, required): The invitation token to reject
Returns: 
{
  status: boolean;
  message: string;
}

​
Usage Examples

​
Creating Private Invites

// Invite a specific user by email
const { status, message } = await authClient.invite.createInvite({
  email: "[email protected]",
  role: "editor",
  shareInviterName: true,
});

if (status) {
  console.log("Invitation sent!");
}

​
Creating Public Invites

// Create a public invite link (no email)
const { status, message } = await authClient.invite.createInvite({
  role: "member",
  maxUses: 10,
  senderResponse: "url",
});

if (status) {
  // message contains the full invitation URL
  console.log("Share this link:", message);
}

​
Handling Invite Activation

// Activate an invite from URL parameter
const params = new URLSearchParams(window.location.search);
const token = params.get('token');

if (token) {
  try {
    const result = await authClient.invite.activateInvite({
      token,
      callbackURL: window.location.origin + '/dashboard',
    });
    
    if (result.action === 'SIGN_IN_UP_REQUIRED') {
      // Redirect to sign in/up
      window.location.href = result.redirectTo;
    } else {
      // Already logged in, role upgraded
      window.location.href = result.redirectTo || '/dashboard';
    }
  } catch (error) {
    console.error('Invalid or expired invite');
  }
}

​
Displaying Invite Details

// Show invite information before accepting
const token = params.get('token');

if (token) {
  try {
    const { inviter, invitation } = await authClient.invite.getInvite({ token });
    
    // Display to user
    console.log(`${inviter.name} invited you to join as ${invitation.role}`);
    
    if (invitation.newAccount) {
      console.log('You will need to create a new account');
    } else {
      console.log('Your existing account will be upgraded');
    }
  } catch (error) {
    console.error('Could not fetch invite details');
  }
}

​
Managing Invitations

// Cancel an invite you created
try {
  await authClient.invite.cancelInvite({ token: inviteToken });
  console.log('Invitation cancelled');
} catch (error) {
  console.error('Could not cancel invitation');
}

// Reject an invite you received
try {
  await authClient.invite.rejectInvite({ token: inviteToken });
  console.log('Invitation rejected');
} catch (error) {
  console.error('Could not reject invitation');
}

​
Error Handling

try {
  await authClient.invite.createInvite({
    email: "[email protected]",
    role: "admin",
  });
} catch (error) {
  if (error.errorCode === "INSUFFICIENT_PERMISSIONS") {
    console.error("You don't have permission to create invites");
  } else if (error.errorCode === "INVALID_TOKEN") {
    console.error("Invalid or expired invite token");
  } else {
    console.error("An error occurred:", error.message);
  }
}

​
Type Safety

The client plugin automatically infers types from your server configuration: 
import type { InviteClientPlugin } from "better-auth-invite-plugin/client";

// Types are automatically inferred
type AuthClient = typeof authClient;
type InviteMethods = AuthClient["invite"];

​
Source Code Reference

Implementation: src/client.ts:4-9

Build docs developers (and LLMs) love

Get started for freeTalk to us