Docs

Invitations

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. When the user visits the invitation link, they will be redirected to the application's sign up page and their email address will be 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 and will have to go through the normal sign-up flow. Their email address will not be auto-verified.

Note

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 restrictions options.

Creating invitations

At the moment, you can only create invitations for email addresses via the Backend API.

You can either use a cURL command or Clerk's JavaScript Backend SDK to create an invitation. Use the 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'

Clerk's Backend SDK is a wrapper around the Backend API that makes it easier to interact with the API.

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

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

Revoking an invitation prevents the user from using the invitation link that was sent to them.

At the moment, you can only revoke invitations via the Backend API.

You can either use a cURL command or Clerk's JavaScript Backend SDK to create an invitation. Use the 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'

Clerk's Backend SDK is a wrapper around the Backend API that makes it easier to interact with the API.

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

Warning

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.

Build a custom flow to handle invitations

Caution

This section is for users who want to build a custom user interface using the Clerk API. To handle invitations using a prebuilt UI, you should use Clerk's Account Portal pages or prebuilt components.

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 create an invitation with the redirect_url set to https://www.example.com/my-sign-up:

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'

Once the user visits the invitation link and is redirected to the specified URL, an invitation token will be appended to the URL.

Using the previous example, the URL with the invitation token would look like this:

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

You can then use the invitation token to create a new sign-up. The following example demonstrates how to create a new sign-up using the invitation token:

app/my-sign-up/page.tsx
import { useSignUp } from "@clerk/nextjs";

const { signUp } = useSignUp();

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

// Optional: collect additional user information
const firstName = "John";
const lastName = "Doe";

// Create a new sign-up with the supplied invitation token.
// Make sure you're also passing the ticket strategy.
// After the below call, the user's email address will be
// automatically verified because of the invitation token.
const response = await signUp.create({
  strategy: "ticket",
  ticket,
  firstName,
  lastName
});

Feedback

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

Last updated on