Skip to main content

​
Endpoint

POST /invite/create
Create a new invitation to invite users to your application. Supports both private invites (with email) and public invites (shareable links).

​
Authentication

This endpoint requires authentication. User must be logged in with a valid session.

​
Request Body

​
role
string
required
The role to assign to the invited user.
"role": "member"
​
email
string
The email address of the user to send an invitation email to. When provided, creates a private invite. When omitted, creates a public invite link.
"email": "[email protected]"
​
tokenType
'token' | 'code' | 'custom'
Type of token to use:
  • "token": 24-character token
  • "code": 6-digit code
  • "custom": Uses options.generateToken
Default: options.defaultTokenType
"tokenType": "code"
​
redirectToSignUp
string
The URL to redirect the user to create their account. If the token is invalid or expired, redirects with ?error=INVALID_TOKEN. If valid, redirects with ?token=VALID_TOKEN.Default: options.defaultRedirectToSignUp
"redirectToSignUp": "/register"
​
redirectToSignIn
string
The URL to redirect the user to upgrade their role.Default: options.defaultRedirectToSignIn
"redirectToSignIn": "/login"
​
maxUses
number
The number of times an invitation can be used.Default: options.defaultMaxUses (1 for private invites, infinite for public invites)
"maxUses": 5
​
expiresIn
number
Number of seconds the invitation token is valid for.Default: options.invitationTokenExpiresIn (3600 seconds / 1 hour)
"expiresIn": 86400
​
redirectToAfterUpgrade
string
The URL to redirect the user to after upgrading their role (if the user is already logged in). {token} will be replaced with the user’s actual token.Default: options.defaultRedirectAfterUpgrade
"redirectToAfterUpgrade": "/dashboard?token={token}"
​
shareInviterName
boolean
Whether the inviter’s name should be shared with the invitee. When enabled, the person receiving the invitation will see the name of the user who created the invitation.Default: options.defaultShareInviterName (true)
"shareInviterName": true
​
senderResponse
'token' | 'url'
How should the sender receive the token. Only applies when no email is provided (public invites).
  • "token": Returns just the token string
  • "url": Returns the complete activation URL
Default: options.defaultSenderResponse (“token”)
"senderResponse": "url"
​
senderResponseRedirect
'signUp' | 'signIn'
Where should the invite redirect the user? Only applies when no email is provided (public invites).Default: options.defaultSenderResponseRedirect (“signUp”)
"senderResponseRedirect": "signIn"
​
customInviteUrl
string
Custom URL pattern for the invitation. Use {token} and {callbackUrl} placeholders, which will be replaced with their actual values.
"customInviteUrl": "https://example.com/invite/{token}?callback={callbackUrl}"

​
Response

​
Success Response (200)

​
status
boolean
Always true on success.
​
message
string
For private invites (with email): "The invitation was sent"For public invites (no email): Contains the token or URL based on senderResponse setting.

​
Examples

​
Private Invite (with Email)

Request: 
POST /invite/create
Content-Type: application/json

{
  "email": "[email protected]",
  "role": "member",
  "tokenType": "code",
  "shareInviterName": true
}
Response: 
{
  "status": true,
  "message": "The invitation was sent"
}
The user at [email protected] will receive an email via the sendUserInvitation function configured in plugin options. Request: 
POST /invite/create
Content-Type: application/json

{
  "role": "member",
  "maxUses": 10,
  "senderResponse": "url",
  "senderResponseRedirect": "signUp"
}
Response: 
{
  "status": true,
  "message": "http://localhost:3000/api/auth/invite/activate?token=abc123xyz789&callbackURL=/auth/sign-up"
}
The message field contains the shareable invitation URL.

​
Invite with Custom Settings

Request: 
POST /invite/create
Content-Type: application/json

{
  "email": "[email protected]",
  "role": "admin",
  "tokenType": "token",
  "maxUses": 1,
  "expiresIn": 86400,
  "redirectToAfterUpgrade": "/admin/dashboard",
  "shareInviterName": false
}
Response: 
{
  "status": true,
  "message": "The invitation was sent"
}

​
Error Responses

​
Insufficient Permissions (400)

{
  "message": "User does not have sufficient permissions to create invite",
  "errorCode": "INSUFFICIENT_PERMISSIONS"
}
Returned when:
  • User doesn’t have permission based on canCreateInvite option
  • User doesn’t meet custom permission requirements

​
Invitation Email Not Enabled (500)

{
  "message": "Invitation email is not enabled"
}
Returned when:
  • Creating a private invite without configuring sendUserInvitation in plugin options

​
Email Sending Failed (500)

{
  "message": "Error sending the invitation email"
}
Returned when:
  • The sendUserInvitation function throws an error

​
Behavior

​
Private Invites (with email)

  1. Checks if the email belongs to an existing user
  2. Determines if this is a new account invitation or role upgrade
  3. Creates invitation record in database
  4. Sends email via sendUserInvitation function
  5. Returns success confirmation

​
Public Invites (without email)

  1. Creates invitation record with no email restriction
  2. Returns token or URL based on senderResponse setting
  3. Token/URL can be shared and used by anyone (up to maxUses times)

​
Hooks

The following hooks are triggered during this endpoint:
  • beforeCreateInvite: Called before creating the invitation
  • afterCreateInvite: Called after the invitation is created successfully

​
Permissions

Permission is checked using the canCreateInvite option: 
// Function-based permission
canCreateInvite: async ({ invitedUser, inviterUser, ctx }) => {
  return inviterUser.role === 'admin';
}

// Permission object
canCreateInvite: {
  statement: "user:invite:create",
  permissions: ["admin", "manager"]
}

​
Source Code Reference

Implementation: src/routes/create-invite.ts:13-193 Body schema: src/body.ts:4-122

Build docs developers (and LLMs) love

Get started for freeTalk to us