Invite users to your organization

Organization invitations allow you to add new members to your organization, granting them access to organization-specific features and resources.

Once you create an invitation, Clerk sends an email to the invited user with a unique invitation link. When the user visits the organization invitation link, they will be redirected to the Account Portal sign-in page. If the user is already signed in, they will be redirected to your application's homepage (/). If you want to redirect the user to a specific page in your application, you can specify a redirect URL when creating the invitation.

Create an invitation

Clerk's prebuilt components and Account Portal pages manage all organization invitation flows, including creating, managing, and accepting invitations.

However, if you want to build custom flows, see the following sections.

Client-side

To create an organization invitation on the client-side, see the dedicated guide. Note that this uses the organizations.inviteMember() method, which does not allow you to specify a redirect URL; it will always redirect to the Account Portal sign-in page. If you want to specify a redirect URL, you must create the invitation on the server-side.

Server-side

You can also create organization invitations via the Backend API either by using a cURL command or the JavaScript Backend SDK. The 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.

curl 'https://api.clerk.com/v1/organizations/<YOUR_ORGANIZATION_ID>/invitations' \
-X POST \
-H 'Authorization: Bearer YOUR_SECRET_KEY' \
-H 'Content-Type: application/json' \
-d '{ "inviter_user_id": "user_123", "email_address": "test@gmail.com", "role": "org:member" }'

See the Backend API guide for 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/organizations/<YOUR_ORGANIZATION_ID>/invitations' \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "inviter_user_id": "user_123", "email_address": "test@gmail.com", "role": "org:member", "redirect_url": "https://www.example.com/accept-invitation" }'

Once the user visits the invitation link, they will be redirected to the page you specified. On that page, you must handle the authentication flow in your code. You can either embed the <SignIn /> component or, if the prebuilt component doesn't meet your needs or you require more control over the logic, you can build a custom flow.

Invitation metadata

You can also add metadata to an invitation when creating the invitation through the Backend API. Once the invited user signs up using the invitation link, the invitation metadata (OrganizationInvitation.public_metadata) will be stored in the organization membership's metadata (OrganizationMembership.publicMetadata). You can find more information about organization membership metadata in the Organization Membership 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/organizations/<YOUR_ORGANIZATION_ID>/invitations' \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "inviter_user_id": "user_123", "email_address": "test@gmail.com", "role": "org:member", "public_metadata": {"department": "marketing"} }'

Revoke an invitation

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

Client-side

To revoke an invitation client-side, see the dedicated guide.

Server-side

To revoke an invitation server-side, you can use the 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.

curl 'https://api.clerk.com/v1/organizations/<YOUR_ORGANIZATION_ID>/invitations/<INVITATION_ID>/revoke' \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "requesting_user_id": "user_123" }'