Invitations

Learn how to invite users to your application

Overview

Clerk makes it easy to invite users to your application via the invitations feature. This feature is offered by default to all Clerk applications without any extra configuration.

All that is needed to do is to create an invitation for an email address. Once the invitation is created, an email with an invitation link will be sent to the user's email address. By clicking on the invitation link, the user will be redirected to the application's sign up page and their email address will have been automatically verified. At this point, the user will just have to fill in the rest of the details according to the application's settings.

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

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 into creating invitation-only applications, please refer to our allowlist feature.

Before you start

You need to create a Clerk Application in your Clerk Dashboard. For more information, check out our Set up your application guide.

Creating invitations

At the moment, you can only create invitations for email addresses via the Backend API. First, you will need to grab your API key which can be found in Clerk Dashboard under API Keys > Backend API Keys.

Once you have that, you can make the following request to the Backend API:

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

This will create a new invitation and send an invitation email to the given email address.

Revoking invitations

Revoking an invitation prevents the user from using the invitation link that was sent to them. In order to revoke an invitation, you can make the following request to the Backend API:

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

The invitation id can be found in the response of the invitation creation request.

Revoking an invitation does not prevent the user from signing up on their own.If you're looking for invitation-only applications, please refer to our allowlist feature.

Invitation metadata

Invitations can optionally carry metadata that will eventually end up in the created user once they sign up. The metadata must be a well-formed JSON object.

In order to add metadata to an invitation, you can use the public_metadata property when the invitation is created:

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

Once an invited user signs up using the invitation link, the invitation metadata will end up in the user's public_metadata. For more information on a user's metadata, please refer to Custom User Metadata.

Custom flow

If you're using Clerk Components, invitation links are handled out of the box. However, if you have built custom sign up and sign in flows using ClerkJS directly, then you'll need to do a little bit of extra work.

The first thing that changes in this case is that during the invitation creation, you will need to specify the url of your sign up page. You can do that by including an additional redirect_url parameter in the invitation creation request.

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

This redirect_url basically tells Clerk where to redirect the user when they click on the invitation link. This redirection will include an invitation token, something like the following:

https://www.example.com/my-sign-up?__clerk_ticket=.....

The second and final thing you'll need to do is to pass this token into the sign up create call, when starting the sign up flow.

1
import { useSignUp } from "@clerk/clerk-react";
2

3
const { signUp } = useSignUp();
4

5
// Get the token from the query parameter
6
const param = '__clerk_ticket';
7
const ticket = new URL(window.location.href).searchParams.get(param);
8

9
// Create a new sign-up with the supplied invitation token.
10
// Make sure you're also passing the ticket strategy.
11
// You can also include any additional information required 
12
// based on your application configuration. Or, you can add 
13
// them later using the `signUp.update` method.
14
// After the below call, the user's email address will be 
15
// verified because of the invitation token.
16
const response = await signUp.create({
17
  strategy: "ticket",
18
  ticket,
19
  firstName,
20
  lastName
21
});

1
const { client } = window.Clerk;
2

3
// Get the token from the query parameter
4
const param = '__clerk_invitation_token';
5
const ticket = new URL(window.location.href).searchParams.get(param);
6

7
// Create a new sign-up with the supplied invitation ticket.
8
// Make sure you're also passing the ticket strategy.
9
// You can also include any additional information required 
10
// based on your application configuration. Or, you can add 
11
// them later using the `signUp.update` method.
12
// After the below call, the user's email address will be 
13
// verified because of the invitation token.
14
const signUp = await client.signUp.create({
15
  strategy: "ticket",
16
  ticket,
17
  firstName,
18
  lastName
19
});