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.
The following example demonstrates how to create an organization invitation using cURL.
Replace the <YOUR_ORGANIZATION_ID> with the ID of the organization you want to invite the user to. Replace the user_123 with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Your Secret Key is already injected into the code snippet.
Replace the <YOUR_ORGANIZATION_ID> with the ID of the organization you want to invite the user to. Replace the user_123 with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Replace YOUR_SECRET_KEY with your Clerk Secret Key. You can find your Secret Key on the API keys page in the Clerk Dashboard.
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.
See the Backend API reference 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.
Replace the <YOUR_ORGANIZATION_ID> with the ID of the organization you want to invite the user to. Replace the user_123 with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Your Secret Key is already injected into the code snippet.
Replace the <YOUR_ORGANIZATION_ID> with the ID of the organization you want to invite the user to. Replace the user_123 with the ID of the user who is inviting the other user. Replace the email address with the email address you want to invite. Replace YOUR_SECRET_KEY with your Clerk Secret Key. You can find your Secret Key on the API keys page in the Clerk Dashboard.
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.
The following example demonstrates how to revoke an invitation using cURL.
Replace the <YOUR_ORGANIZATION_ID> with the ID of the organization you want to revoke the invitation from. Replace the <INVITATION_ID> with the ID of the invitation you want to revoke. Replace user_123 with the ID of the user who is revoking the invitation. Your Secret Key is already injected into the code snippet.
Replace the <YOUR_ORGANIZATION_ID> with the ID of the organization you want to revoke the invitation from. Replace the <INVITATION_ID> with the ID of the invitation you want to revoke. Replace user_123 with the ID of the user who is revoking the invitation. Replace YOUR_SECRET_KEY with your Clerk Secret Key. You can find your Secret Key on the API keys page in the Clerk Dashboard.
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
Last updated on