Invite an application user
An administrator needs to add a person to an application by email.
Clerk · Module
invitations.createInvitation
Creates an application invitation for an email address and sends the invitation email by default. It returns the newly created Invitation resource.
How it works
Call the Backend SDK method with the recipient's email and optional delivery and redirect settings. Clerk creates the invitation, sends its email by default, and returns the resulting Invitation resource.
Syntax
function createInvitation(params: CreateParams): Promise<Invitation>Parameters
| Name | Type | Description |
|---|---|---|
emailAddress | string | The email address of the user to invite. |
expiresInDays? | number | The number of days until the invitation expires; defaults to 30. |
ignoreExisting? | boolean | Whether to create an invitation when an invitation or user already exists; defaults to false. |
notify? | boolean | Whether an email invitation is sent; defaults to true. |
redirectUrl? | string | The full URL or path where the user lands after accepting the invitation. |
publicMetadata? | object | Additional metadata associated with the invitation. |
Returns
Promise<Invitation>
Key points
- The method creates an application invitation for the supplied email address and normally sends the invitation email.
- Use expiresInDays to set how long the invitation remains valid.
- If no expiration is supplied, the invitation expires after 30 days.
- The notify option determines whether Clerk sends the invitation email.
- Notification is enabled unless notify is explicitly set to false.
- redirectUrl chooses the destination after the recipient accepts the invitation.
Common mistakes
- The endpoint is limited to 100 requests per hour for each application instance.
- A duplicate invitation or an address already present in the application causes an error unless duplicate handling is enabled.
- Set ignoreExisting to true when a new invitation must be created despite an existing invitation or user.
Example: Create an application invitation
import { createClerkClient } from '@clerk/backend'
const clerkClient = createClerkClient({
secretKey: process.env.CLERK_SECRET_KEY,
})
const invitation = await clerkClient.invitations.createInvitation({
emailAddress: 'invite@example.com',
redirectUrl: 'https://www.example.com/my-sign-up',
publicMetadata: { source: 'admin' },
})
console.log(invitation.id)Creates and sends an application invitation, then logs the returned invitation identifier.
When to use it
Redirect after acceptance
A product needs invitation links to open a custom onboarding route.
Store invitation metadata
An integration must attach structured context to an invitation.
Interview questions
QWhat does invitations.createInvitation return and what is its purpose?
It creates an application invitation for an email address, sends the invitation email, and resolves to the newly created Invitation. The method signature is createInvitation(params: CreateParams): Promise<Invitation>.
Follow-up: What happens for an already invited address? By default the call errors; setting ignoreExisting to true allows creation of another invitation.
QWhich important parameters control invitation lifetime and notification?
emailAddress identifies the recipient and is required. expiresInDays controls the lifetime and defaults to 30, while notify controls email delivery and defaults to true.
Follow-up: How would you prevent an email from being sent? Pass notify: false while still creating the invitation.
QWhat operational constraint and post-acceptance setting should an implementation consider?
The optional redirectUrl specifies the full URL or path where the user lands after accepting the invitation. The method is rate limited to 100 requests per hour per application instance.
Follow-up: How can multiple users be invited in one request? Use the separate createInvitationBulk() method.
Related
createInvitationBulk()InvitationclerkClientCreateParams