Invitations

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. Currently, Clerk supports inviting users via email.

Inviting users to your application begins with creating 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.

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.

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. You can find more information about user metadata in the metadata docs.

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.

import { useSignUp } from "@clerk/clerk-react";
 
const { signUp } = useSignUp();
 
// Get the token from the query parameter
const param = '__clerk_ticket';
const ticket = new URL(window.location.href).searchParams.get(param);
 
// Create a new sign-up with the supplied invitation token.
// Make sure you're also passing the ticket strategy.
// You can also include any additional information required 
// based on your application configuration. Or, you can add 
// them later using the `signUp.update` method.
// After the below call, the user's email address will be 
// verified because of the invitation token.
const response = await signUp.create({
  strategy: "ticket",
  ticket,
  firstName,
  lastName
});

const { client } = window.Clerk;
 
// Get the token from the query parameter
const param = '__clerk_invitation_token';
const ticket = new URL(window.location.href).searchParams.get(param);
 
// Create a new sign-up with the supplied invitation ticket.
// Make sure you're also passing the ticket strategy.
// You can also include any additional information required 
// based on your application configuration. Or, you can add 
// them later using the `signUp.update` method.
// After the below call, the user's email address will be 
// verified because of the invitation token.
const signUp = await client.signUp.create({
  strategy: "ticket",
  ticket,
  firstName,
  lastName
});