Build a custom flow for inviting users to an organization
Organization members with appropriate permissions can invite new users to their organization and manage those invitations. When an administrator invites a new member, an invitation email is sent out. The invitation recipient can be either an existing user of your application or a new user. If the latter is true, the user will need to register in order to accept the invitation.
Users with the appropriate permissions can also revoke organization invitations for users that have not yet joined, which will prevent the user from becoming an organization member.
This guide will demonstrate how to use Clerk's API to build a custom flow for inviting users to an organization and listing an organization's pending invitations.
To invite a user:
- Use the
useOrganization()
hook to getorganization
, which is the active organization. - Use
organization
to call theinviteMember()
method, with the recipient's email address and desired role passed as arguments.
To revoke an invitation:
- Use the
useOrganization()
hook to getinvitations
, which is a list of invitations for the active organization. invitations
is an array ofOrganizationInvitation
objects. EachOrganizationInvitation
object has arevoke()
method that can be called to revoke the invitation.
The following example includes:
- An
<InviteMember />
component that allows administrators to invite new members to their organization. - An
<InvitationList />
component that lists all pending invitations and allows administrators to revoke them.
This example is written for Next.js App Router but can be adapted for any React meta framework, such as Remix or Gatsby.
To check if the current user is an organization admin:
- Get the active organization's ID from the
clerk
object. - Call the
getOrganizationMemberships()
method to get a list of organizations that the user is a member of. This method returnsdata
, which is an array ofOrganizationMembership
objects. - In the list of organizations that the user is a member of, find the
OrganizationMembership
object that has an ID that matches the active organization's ID. - Check the
role
property of theOrganizationMembership
object to see if the user is an admin.
To invite a user:
- Use the active
organization
object to call theinviteMember()
method, with the recipient's email address and desired role passed as arguments.
To revoke an invitation:
- Use the active
organization
object to call thegetInvitations()
method to get an array ofOrganizationInvitation
objects. - Each
OrganizationInvitation
object has arevoke()
method that can be called to revoke the invitation.
The following example includes:
- A
renderInvitations()
function that lists all invitations and allows administrators to revoke them. - An
checkAdminAndRenderInvitations()
function that gets the current organization, checks if the current user is an admin, renders invitations, and sets up a form that allows administrators to invite new members to their organization.
Use the tabs to view the code necessary for the index.html
and main.js
files.
Custom redirect URL
When creating an organization invitation and using Clerk's Next.js, Remix, or Backend SDKs, you can specify a custom redirect URL. After users click on organization invitation link and the ticket is verified, they will get redirected to that URL. The URL will contain two important query parameters added by Clerk: __clerk_ticket
and __clerk_status
.
The __clerk_ticket
query parameter will hold the actual ticket token, which can be used during sign-in and sign-up flows in order to complete the organization invitation flow.
The __clerk_status
query parameter is the outcome of the ticket verification and will contain one of three values:
sign_in
indicates the user already exists in your application. You should create a sign-in ticket in order to complete the flow.sign_up
indicates the user doesn't already exist in your application. You should create a sign-up ticket in order to complete the flow.complete
indicates the user already exists in your application, and was signed in. The flow has been completed and no further actions are required.
An example implementation on how to create an invitation by providing a redirect url using Clerk backend SDK:
Feedback
Last updated on