Docs

Invite users to your application

Inviting users to your Clerk application allows you to onboard new users seamlessly by sending them a unique invitation link.

Once you create an invitation, Clerk sends an email to the invited user with a unique invitation link. When the user visits the invitation link, they will be redirected to Clerk's Account Portal sign-up page and their email address will be automatically verified. If you want to redirect the user to a specific page in your application, you can specify a redirect URL when creating the invitation.

Invitations expire after a month. If the user clicks on an expired invitation, they will get redirected to the application's sign-up page and will have to go through the normal sign-up flow. Their email address will not be auto-verified.

Tip

Invitations are only used to invite users to your application. The application will still be available to everyone even without an invitation. If you're looking to restrict access to invited users only, please refer to Clerk's Restricted sign-up mode.

Create an invitation

You can create an invitation in the Clerk Dashboard or using the Backend API.

Using Clerk Dashboard

To invite users, navigate to the Users page from the top-level menu, then select the Invitations tab. Select Invite user and enter the email address of the person you want to invite. Optionally, set an expiration date for the invitation. Once you've entered the necessary details, click Send invite to send the invitation email.

Tip

The same page will be available throught the top-level menu, when you are in the Restricted sign-up mode.

Using Backend API

You can either use a cURL command or Clerk's JavaScript Backend SDK to create an invitation. Clerk's JavaScript Backend SDK is a wrapper around the Backend API that makes it easier to interact with the API. Use the following tabs to see examples for each method.

The following example demonstrates how to create an invitation using cURL.

terminal
curl https://api.clerk.com/v1/invitations -X POST -d '{"email_address": "email@example.com"}' -H "Authorization:Bearer YOUR_SECRET_KEY" -H 'Content-Type:application/json'

To use the Backend SDK to create an invitation, see the createInvitation() reference.

Check out the Backend API reference to see an example of the response.

Redirect URL

When you create an invitation, you can specify a redirect_url parameter. This parameter tells Clerk where to redirect the user when they visit the invitation link.

The following example demonstrates how to use cURL to create an invitation with the redirect_url set to https://www.example.com/accept-invitation:

curl https://api.clerk.com/v1/invitations -X POST -d '{"email_address": "email@example.com", "redirect_url": "https://www.example.com/accept-invitation"}' -H "Authorization:Bearer YOUR_SECRET_KEY" -H 'Content-Type:application/json'

Once the user visits the invitation link, they will be redirected to the page you specified, which means you must handle the sign-up flow in your code for that page. You can either embed Clerk's <SignUp /> component on that page, or if the prebuilt component doesn't meet your specific needs or if you require more control over the logic, you can build a custom flow.

Tip

For testing redirect URL's in your development environment, you can pass your port (http://localhost:3000). If you would like to use Clerk's Account Portal, you can pass your Clerk Frontend API URL as the base URL. For example, https://prepared-phoenix-98.clerk.accounts.dev/sign-up would send the user to the Account Portal sign-up page. You can find your Frontend API URL in the Clerk Dashboard on the API Keys page. On the left side, select Show API URLs.

Invitation metadata

You can also add metadata to an invitation. Once the invited user signs up using the invitation link, the invitation metadata will end up in the user's public_metadata. You can find more information about user metadata in the metadata docs.

To add metadata to an invitation, you can use the public_metadata property when the invitation is created.

The following example demonstrates how to create an invitation with metadata using cURL.

curl https://api.clerk.com/v1/invitations -X POST -d '{"email_address": "email@example.com", "public_metadata": {"age": "21"}}' -H "Authorization:Bearer YOUR_SECRET_KEY" -H 'Content-Type:application/json'

Revoking invitations

You can revoke an invitation at any time. Revoking an invitation prevents the user from using the invitation link that was sent to them.

Using Clerk Dashboard

To revoke an invitation, navigate to the Users page from the top-level menu, then select the Invitations tab. Find the invitation you want to revoke and select Revoke from the dropdown menu on the right.

Tip

The same page will be available throught the top-level menu, when you are in the Restricted sign-up mode.

Using Backend API

You can either use a cURL command or Clerk's JavaScript Backend SDK to create an invitation. Use the following tabs to see examples for each method.

The following example demonstrates how to revoke an invitation using cURL.

terminal
curl https://api.clerk.com/v1/invitations/<invitation_id>/revoke -X POST -H "Authorization:Bearer YOUR_SECRET_KEY" -H 'Content-Type:application/json'

To use the Backend SDK to revoke an invitation, see the revokeInvitation() reference documentation.

Check out the Backend API reference to see an example of the response.

Warning

Revoking an invitation does not prevent the user from signing up on their own. If you're looking to restrict access to invited users only, please refer to Clerk's Restricted sign-up mode.

Custom flow

Clerk's prebuilt components and Account Portal pages handle the sign-up flow for you, including the invitation flow. If you want to build a custom sign-up flow, see the custom flow guide.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on