|
1 | 1 | --- |
2 | | -title: Invite users to your organization |
3 | | -description: Send, manage, and track user invitations within your multi-tenant SaaS using Clerk organizations. |
| 2 | +title: Invite users to your Organization |
| 3 | +description: Send, manage, and track user invitations within your multi-tenant SaaS using Clerk Organizations. |
4 | 4 | metadata: |
5 | | - title: Send and manage organization invitations via Clerk |
| 5 | + title: Send and manage Organization invitations via Clerk |
6 | 6 | --- |
7 | 7 |
|
8 | | -Organization invitations let you add new members to your organization. When you send an invitation, Clerk sends an email to the invited user with a unique invitation link. When the user visits the organization invitation link, Clerk redirects them to the [Account Portal sign-in page](/docs/guides/customizing-clerk/account-portal#sign-in). If the user is already signed in, Clerk redirects them 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](#redirect-url). |
| 8 | +Organization invitations let you add new members to your Organization. When you send an invitation, Clerk sends an email to the invited user with a unique invitation link. When the user visits the Organization invitation link, Clerk redirects them to the [Account Portal sign-in page](/docs/guides/customizing-clerk/account-portal#sign-in). If the user is already signed in, Clerk redirects them 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](#redirect-url). |
9 | 9 |
|
10 | | -By default, only [admins](/docs/guides/organizations/control-access/roles-and-permissions#default-roles) can invite users to an organization. |
| 10 | +By default, only [admins](/docs/guides/organizations/control-access/roles-and-permissions#default-roles) can invite users to an Organization. |
11 | 11 |
|
12 | 12 | This feature requires that [**Email** is enabled](/docs/guides/configure/auth-strategies/sign-up-sign-in-options#email), as Clerk uses the user's email address to send the invitation. You can still disable **Email** as a sign-in option if you do not want users to be able to sign-in with their email address. |
13 | 13 |
|
14 | 14 | To configure your application's **Email** settings, navigate to the [**User & authentication**](https://dashboard.clerk.com/~/user-authentication/user-and-authentication) page in the Clerk Dashboard. |
15 | 15 |
|
16 | 16 | ## When to use invitations |
17 | 17 |
|
18 | | -Invitations work well when you need precise control over who joins your organization and which role they receive. This approach fits scenarios where: |
| 18 | +Invitations work well when you need precise control over who joins your Organization and which Role they receive. This approach fits scenarios where: |
19 | 19 |
|
20 | 20 | - Teams are small and members are known in advance. |
21 | 21 | - Onboarding requires manual approval or review. |
22 | | -- Specific roles need to be assigned during the invitation. |
| 22 | +- Specific Roles need to be assigned during the invitation. |
23 | 23 |
|
24 | | -If you want to streamline enrollment for users with company email addresses, consider [verified domains](/docs/guides/organizations/add-members/verified-domains), which can automatically invite users based on their email domain. If customers require centralized authentication through their Identity Provider, use [enterprise SSO](/docs/guides/organizations/add-members/sso). |
| 24 | +If you want to streamline enrollment for users with company email addresses, consider [Verified Domains](/docs/guides/organizations/add-members/verified-domains), which can automatically invite users based on their email domain. If customers require centralized authentication through their Identity Provider, use [Enterprise SSO](/docs/guides/organizations/add-members/sso). |
25 | 25 |
|
26 | 26 | ## Create an invitation |
27 | 27 |
|
28 | | -Clerk's [prebuilt components](/docs/reference/components/overview) and [Account Portal pages](/docs/guides/customizing-clerk/account-portal) manage all organization invitation flows, including creating, managing, and accepting invitations. |
| 28 | +Clerk's [prebuilt components](/docs/reference/components/overview) and [Account Portal pages](/docs/guides/customizing-clerk/account-portal) manage all Organization invitation flows, including creating, managing, and accepting invitations. |
29 | 29 |
|
30 | 30 | However, if you want to build custom flows, see the following sections. |
31 | 31 |
|
32 | 32 | ### Client-side |
33 | 33 |
|
34 | | -To create an organization invitation on the client-side, see the [dedicated guide](/docs/guides/development/custom-flows/organizations/manage-organization-invitations). Note that this uses the [`organizations.inviteMember()`](/docs/reference/javascript/organization#invite-member) method, which does not let you 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. |
| 34 | +To create an Organization invitation on the client-side, see the [dedicated guide](/docs/guides/development/custom-flows/organizations/manage-organization-invitations). Note that this uses the [`organizations.inviteMember()`](/docs/reference/javascript/organization#invite-member) method, which does not let you 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. |
35 | 35 |
|
36 | 36 | ### Server-side |
37 | 37 |
|
38 | | -To create organization invitations on the server-side, use the [Backend API](/docs/reference/backend-api/tag/organization-invitations/post/organizations/\{organization_id}/invitations){{ target: '_blank' }} either by using a cURL command or the [JS Backend SDK](/docs/js-backend/getting-started/quickstart). The JS Backend SDK is a wrapper around the Backend API that makes it easier to interact with the API. |
| 38 | +To create Organization invitations on the server-side, use the [Backend API](/docs/reference/backend-api/tag/organization-invitations/post/organizations/\{organization_id}/invitations){{ target: '_blank' }} either by using a cURL command or the [JS Backend SDK](/docs/js-backend/getting-started/quickstart). The JS Backend SDK is a wrapper around the Backend API that makes it easier to interact with the API. |
39 | 39 |
|
40 | 40 | Use the following tabs to see examples for each method. |
41 | 41 |
|
42 | 42 | <Tabs items={["cURL", "JS Backend SDK"]}> |
43 | 43 | <Tab> |
44 | | - The following example demonstrates how to create an organization invitation using cURL. |
| 44 | + The following example demonstrates how to create an Organization invitation using cURL. |
45 | 45 |
|
46 | 46 | <SignedIn> |
47 | 47 | - Your Secret Key is already injected into the code snippet. |
48 | | - - Replace the `org_123` with the ID of the organization you want to invite the user to. |
| 48 | + - Replace the `org_123` with the ID of the Organization you want to invite the user to. |
49 | 49 | - Replace the `user_123` with the ID of the user who is inviting the other user. |
50 | 50 | - Replace the email address with the email address you want to invite. |
51 | 51 | - Replace the `role` with the role you want to assign to the invited user. |
52 | 52 | </SignedIn> |
53 | 53 |
|
54 | 54 | <SignedOut> |
55 | 55 | - Replace `YOUR_SECRET_KEY` with your Clerk Secret Key. You can find your Secret Key on the [**API Keys**](https://dashboard.clerk.com/~/api-keys) page in the Clerk Dashboard. |
56 | | - - Replace the `org_123` with the ID of the organization you want to invite the user to. |
| 56 | + - Replace the `org_123` with the ID of the Organization you want to invite the user to. |
57 | 57 | - Replace the `user_123` with the ID of the user who is inviting the other user. |
58 | 58 | - Replace the email address with the email address you want to invite. |
59 | | - - Replace the `role` with the role you want to assign to the invited user. |
| 59 | + - Replace the `role` with the Role you want to assign to the invited user. |
60 | 60 | </SignedOut> |
61 | 61 |
|
62 | 62 | ```bash {{ filename: 'terminal' }} |
@@ -97,7 +97,7 @@ Once the user visits the invitation link, they will be redirected to the page yo |
97 | 97 |
|
98 | 98 | ### Invitation metadata |
99 | 99 |
|
100 | | -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, Clerk stores the **invitation** metadata (`OrganizationInvitation.publicMetadata`) in the organization **membership's** metadata (`OrganizationMembership.publicMetadata`). For more details on organization membership metadata, see the [OrganizationMembership](/docs/reference/javascript/types/organization-membership) reference. |
| 100 | +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, Clerk stores the **invitation** metadata (`OrganizationInvitation.publicMetadata`) in the Organization **membership's** metadata (`OrganizationMembership.publicMetadata`). For more details on Organization membership metadata, see the [OrganizationMembership](/docs/reference/javascript/types/organization-membership) reference. |
101 | 101 |
|
102 | 102 | To add metadata to an invitation, add the `public_metadata` parameter when creating the invitation. |
103 | 103 |
|
@@ -151,15 +151,15 @@ Use the following tabs to see examples for each method. |
151 | 151 | </Tab> |
152 | 152 |
|
153 | 153 | <Tab> |
154 | | - To use the JS Backend SDK to revoke an organization invitation, see the [`revokeOrganizationInvitation()`](/docs/reference/backend/organization/revoke-organization-invitation) reference documentation. |
| 154 | + To use the JS Backend SDK to revoke an Organization invitation, see the [`revokeOrganizationInvitation()`](/docs/reference/backend/organization/revoke-organization-invitation) reference documentation. |
155 | 155 | </Tab> |
156 | 156 | </Tabs> |
157 | 157 |
|
158 | 158 | ## Next steps |
159 | 159 |
|
160 | | -Now that you know how to invite users to your organization, you can: |
| 160 | +Now that you know how to invite users to your Organization, you can: |
161 | 161 |
|
162 | | -- [Configure verified domains](/docs/guides/organizations/add-members/verified-domains) to automatically invite users based on their email domain |
163 | | -- [Set up enterprise SSO](/docs/guides/organizations/add-members/sso) for centralized authentication through an Identity Provider |
164 | | -- [Set up roles and permissions](/docs/guides/organizations/control-access/roles-and-permissions) to control what invited users can access |
| 162 | +- [Configure Verified Domains](/docs/guides/organizations/add-members/verified-domains) to automatically invite users based on their email domain |
| 163 | +- [Set up Enterprise SSO Connections](/docs/guides/organizations/add-members/sso) for centralized authentication through an Identity Provider |
| 164 | +- [Set up Roles and Permissions](/docs/guides/organizations/control-access/roles-and-permissions) to control what invited users can access |
165 | 165 | - [Add metadata to invitations](/docs/guides/organizations/metadata) for tracking or custom workflows |
0 commit comments