Docs

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 Clerk's 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 Clerk's JavaScript Backend SDK. 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 organization invitation using cURL.

terminal
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" }'

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

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/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 Clerk's <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.

Tip

For testing redirect URLs in your development environment, you can pass your port (http://localhost:3000). If you'd like to use Clerk's Account Portal, pass your Clerk Frontend API URL as the base URL. For example, https://prepared-phoenix-98.clerk.accounts.dev/sign-up redirects 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. In the left sidebar, select Show API URLs.

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 user's metadata (User.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/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": {"age": "21"} }'

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.

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

terminal
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" }'

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

Feedback

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

Last updated on