From d61227c20280fd972c9562d7afde8fbf0d0c288a Mon Sep 17 00:00:00 2001 From: Jeff Escalante Date: Wed, 6 Nov 2024 18:49:41 -0500 Subject: [PATCH 1/8] add a guide detailing how to create orgs on users' behalf --- docs/guides/creating-orgs-for-users.mdx | 39 +++++++++++++++++++++++++ docs/manifest.json | 4 +++ 2 files changed, 43 insertions(+) create mode 100644 docs/guides/creating-orgs-for-users.mdx diff --git a/docs/guides/creating-orgs-for-users.mdx b/docs/guides/creating-orgs-for-users.mdx new file mode 100644 index 0000000000..568480c01b --- /dev/null +++ b/docs/guides/creating-orgs-for-users.mdx @@ -0,0 +1,39 @@ +--- +title: Recommended Architecture for Creating Organizations on Users' Behalf +description: Learn how to architectect your application to create organizations on users' behalf without running into rate limits and billing issues. +--- + +In some cases, you may want the onboarding you your application to include the creation of an organization on the user's behalf. This could be for a number of reasons, such as: + +- You would like for users to your application to be manually onboarded by sales staff and sent an invite to join via an organization created for them. +- Your application only makes sense if the user is part of an organization, and you want to create the organization on the user's behalf as part of the onboarding process. +- You would like to have an "admin account" that has access to all organizations across your application, and can achieve this easily by creating an organization on the user's behalf, rather than allowing the user to create their own organization. + +If this sounds like it fits your use case, this guide will walk you through how to architect your application in this way without running into unexpected rate limits or billing issues, which can be a common problem when creating organizations on behalf of users with Clerk. + +## Recommended Flow + +The recommended approach to ensuring that all users are in an organization is to implement an [onboarding flow](/docs/guides/add-onboarding-flow) in which it's required to create an organization before the user is able to access the application. You can use tools like the [`` component](/docs/components/organization/create-organization) to allow the user to create and name their own organization, or you can use Clerk's [Backend API](/docs/reference/backend-api/tag/Organizations#operation/CreateOrganization) or one of our backend SDKs like the [JS Backend SDK](/docs/references/backend/organization/create-organization) to create an organization on the user's behalf and name it as you'd like. + +If you'd like to have the your onboarding flow involve the user being invited to join your app via an email, you can use Clerk's [invitation functionality](/docs/users/invitations) to accomplish this. So the overall flow would look as such: + +- User receives an invitation to join your application +- Upon clicking the invitation, user registers their account and enters the onboarding flow +- User creates an organization as part of the onboarding flow, and is able to invite colleagues if relevant +- You now have a user that can access your application and is guaranteed to be in an organization + +If you'd also like to enable users to join an existing organization that matches their email domain if one exists, as an alternative to creating a new organization, you can use Clerk's [verified domains](/docs/organizations/verified-domains) feature to accomplish this. + +## You'd like admin access to all organizations in your app + +The easiest way to grant someone on your team admin access to all organizations in your app is to add them as a member to organization on clerk.com. Through Clerk's dashboard, you can see all of the organizations for each of your apps, and take administrative actions, such as adding or removing members, renaming, or deleting an organization. + +If for some reason this is not an option, you can use Clerk's [Backend API](/docs/reference/backend-api) or one of our backend SDKs like the [JS Backend SDK](/docs/references/backend/overview), alongside [roles and permissions](/docs/organizations/roles-permissions) to create a custom admin dashboard through which authorized users can can take adminstrative actions for organizations. + +## Not recommended: using an admin account to create organizations for users + +Although it may seem like a reasonable option, we strongly recommend against using a single admin account to create organizations on the behalf of users. Generally, this is because it can create unexpectedly high costs due to the way that organizations are billed. Let's walk through an example to see why. + +Imagine that you have an admin account that is configured to create organizations on a user's behalf during onboarding, then send an invitation to the user to join the organization. When the user accepts the invitation, their organization has an unneccessary extra admin account in it, and additionally at that point, the organization has two monthly active users (MAUs), which make it a active organization. All [Clerk plans](https://clerk.com/pricing) come with 100 active organizations included for free, but over that limit, organizations are billed at $1/month/org. This means that for every user that is created in your app, they have an active organization automatically, because of the fact that the admin account is also in the organization. This tends to result in much higher costs than if users' organizations are created without an admin account included. Additionally, it's generally a nicer user experience for users not to have extra admin accounts in their organizations. + +If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, please reach out to us at [support@clerk.com](mailto:support@clerk.com) and we'll be happy to help think through a suitable solution. \ No newline at end of file diff --git a/docs/manifest.json b/docs/manifest.json index 8bbb9087a2..71afa21beb 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -134,6 +134,10 @@ { "title": "Override Clerk interfaces with custom types", "href": "/docs/guides/custom-types" + }, + { + "title": "Creating Organizations on Users' Behalf", + "href": "/docs/guides/creating-orgs-for-users" } ] ] From 7b34c622478537044af4fa09954545762f67a687 Mon Sep 17 00:00:00 2001 From: Jeff Escalante Date: Wed, 6 Nov 2024 19:02:32 -0500 Subject: [PATCH 2/8] lint fix --- docs/guides/creating-orgs-for-users.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/creating-orgs-for-users.mdx b/docs/guides/creating-orgs-for-users.mdx index 568480c01b..307fd3c2f6 100644 --- a/docs/guides/creating-orgs-for-users.mdx +++ b/docs/guides/creating-orgs-for-users.mdx @@ -36,4 +36,4 @@ Although it may seem like a reasonable option, we strongly recommend against usi Imagine that you have an admin account that is configured to create organizations on a user's behalf during onboarding, then send an invitation to the user to join the organization. When the user accepts the invitation, their organization has an unneccessary extra admin account in it, and additionally at that point, the organization has two monthly active users (MAUs), which make it a active organization. All [Clerk plans](https://clerk.com/pricing) come with 100 active organizations included for free, but over that limit, organizations are billed at $1/month/org. This means that for every user that is created in your app, they have an active organization automatically, because of the fact that the admin account is also in the organization. This tends to result in much higher costs than if users' organizations are created without an admin account included. Additionally, it's generally a nicer user experience for users not to have extra admin accounts in their organizations. -If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, please reach out to us at [support@clerk.com](mailto:support@clerk.com) and we'll be happy to help think through a suitable solution. \ No newline at end of file +If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, please reach out to us at [support@clerk.com](mailto:support@clerk.com) and we'll be happy to help think through a suitable solution. From 30c8a5432b43478f5977b4fd244142155027aeba Mon Sep 17 00:00:00 2001 From: Jeff Escalante Date: Fri, 8 Nov 2024 21:25:24 -0500 Subject: [PATCH 3/8] Update docs/guides/creating-orgs-for-users.mdx Co-authored-by: victoria --- docs/guides/creating-orgs-for-users.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/guides/creating-orgs-for-users.mdx b/docs/guides/creating-orgs-for-users.mdx index 307fd3c2f6..9dcbccb7ad 100644 --- a/docs/guides/creating-orgs-for-users.mdx +++ b/docs/guides/creating-orgs-for-users.mdx @@ -3,13 +3,14 @@ title: Recommended Architecture for Creating Organizations on Users' Behalf description: Learn how to architectect your application to create organizations on users' behalf without running into rate limits and billing issues. --- -In some cases, you may want the onboarding you your application to include the creation of an organization on the user's behalf. This could be for a number of reasons, such as: +This guide explains how to create organizations on behalf of users for your app. In some use cases, it might be beneficial to create an org for a user automatically during onboarding to ensure all users belong to an org from the start. -- You would like for users to your application to be manually onboarded by sales staff and sent an invite to join via an organization created for them. -- Your application only makes sense if the user is part of an organization, and you want to create the organization on the user's behalf as part of the onboarding process. -- You would like to have an "admin account" that has access to all organizations across your application, and can achieve this easily by creating an organization on the user's behalf, rather than allowing the user to create their own organization. +Example use cases: +- You'd like users to be manually onboarded by sales staff and sent an invite to join through an org created for them. +- Your app only functions if users are part of an org, and you want to create the org for them during onboarding. +- You need an "admin account" with access to all orgs in your app, which can be achieved by creating orgs on users' behalf instead of allowing them to create their own. -If this sounds like it fits your use case, this guide will walk you through how to architect your application in this way without running into unexpected rate limits or billing issues, which can be a common problem when creating organizations on behalf of users with Clerk. +With the recommended setup, you can avoid unexpected rate limits, billing issues, and poor user experience. ## Recommended Flow From eb6f7be0b8e79a04bb59f1c38cfae02037ec6a02 Mon Sep 17 00:00:00 2001 From: Jeff Escalante Date: Wed, 13 Nov 2024 17:00:49 -0500 Subject: [PATCH 4/8] copy edit updates --- docs/guides/create-orgs-for-users.mdx | 39 ++++++++++++++++++++++++ docs/guides/creating-orgs-for-users.mdx | 40 ------------------------- docs/manifest.json | 4 +-- 3 files changed, 41 insertions(+), 42 deletions(-) create mode 100644 docs/guides/create-orgs-for-users.mdx delete mode 100644 docs/guides/creating-orgs-for-users.mdx diff --git a/docs/guides/create-orgs-for-users.mdx b/docs/guides/create-orgs-for-users.mdx new file mode 100644 index 0000000000..341ad3b3db --- /dev/null +++ b/docs/guides/create-orgs-for-users.mdx @@ -0,0 +1,39 @@ +--- +title: Create organizations on behalf of users +description: Learn how to architect your application to create organizations on users' behalf without running into rate limits and billing issues. +--- + +In some cases, you may want the onboarding for your app to include the creation of an organization on the user's behalf. This could be for a number of reasons, such as: + +- You would like for users to your application to be manually onboarded by sales staff and sent an invite to join via an organization created for them. +- Your application only makes sense if the user is part of an organization, and you want to create the organization on the user's behalf as part of the onboarding process. +- You would like to have an "admin account" that has access to all organizations across your application, and can achieve this easily by creating an organization for the user with an admin account, rather than allowing the user to create their own organization. + +If this sounds like it fits your use case, this guide will walk you through how to architect your application without running into unexpected rate limits or billing issues, which can be a common problem when creating organizations on behalf of users. + +## Recommended: require users to create orgs during onboarding + +The recommended approach to ensure that all users are in an organization is to implement an [onboarding flow](/docs/guides/add-onboarding-flow) in which it's required to create an organization before the user is able to access the app. You can use tools like the [`` component](/docs/components/organization/create-organization) to allow the user to create and name their own organization, or you can use the [Backend API](/docs/reference/backend-api/tag/Organizations#operation/CreateOrganization) or a backend SDK like the [JS Backend SDK](/docs/references/backend/organization/create-organization) to create an organization on the user's behalf. + +If you'd like to have the onboarding flow include inviting users via email, use the [invitation feature](/docs/users/invitations). The flow would look like this: + +- User receives an invitation to join your app via email. +- User clicks the invitation link, registers an account, and enters the onboarding flow. +- User creates an organization as part of the onboarding flow, and can invite other users if needed. +- The user can now access your app and is part of an org. + +If you'd like to enable users to join an existing org that matches their email domain (if one exists) as an alternative to creating a new organization, use the [verified domains](/docs/organizations/verified-domains) feature. + +## Not recommended: use an admin account to create organizations for users + +Although it may seem like a reasonable option, it's strongly recommended not to use a single admin account to create organizations on the behalf of users. Generally, this is because it can create unexpectedly high costs due to the way that organizations are billed. Let's walk through an example to see why. + +Imagine that you have an admin account that is configured to create organizations on a user's behalf during onboarding, then sends an invitation to the user to join the organization. When the user accepts the invitation, their organization has an unneccessary extra admin account in it, and additionally at that point, the organization has two monthly active users (MAUs), which makes it a active organization. All [Clerk plans](https://clerk.com/pricing) come with 100 active organizations included for free, but over that limit, organizations are billed at $1 per month per org. In this case, for every user that is created in your app, they have an active organization automatically, because of the fact that the admin account is also in the organization. This tends to result in much higher costs than if users' organizations are created without an admin account included, since orgs with only one active user are not billable. Additionally, it's generally a nicer experience for users not to have extra admin accounts in their organizations. + +If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, reach out to us at [support@clerk.com](mailto:support@clerk.com) and we'll be happy to help think through a suitable solution. + +## Grant a user access to all orgs + +The simplest way to grant someone on your team access to all orgs in your app is to add them as a member to your [organization workspace](/docs/organizations/organization-workspaces) in the Clerk Dashboard. Members of your organization workspace, also known as collaborators, can view all of the orgs for each of your apps and perform administrative actions, such as adding or removing members, renaming an org, or deleting an org. + +If this isn't an option, you can use the [Backend API](/docs/reference/backend-api) or a backend SDK, such as the [JS Backend SDK](/docs/references/backend/overview), along with [roles and permissions](/docs/organizations/roles-permissions) to create a custom admin dashboard where authorized users can take adminstrative actions for orgs. \ No newline at end of file diff --git a/docs/guides/creating-orgs-for-users.mdx b/docs/guides/creating-orgs-for-users.mdx deleted file mode 100644 index 9dcbccb7ad..0000000000 --- a/docs/guides/creating-orgs-for-users.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Recommended Architecture for Creating Organizations on Users' Behalf -description: Learn how to architectect your application to create organizations on users' behalf without running into rate limits and billing issues. ---- - -This guide explains how to create organizations on behalf of users for your app. In some use cases, it might be beneficial to create an org for a user automatically during onboarding to ensure all users belong to an org from the start. - -Example use cases: -- You'd like users to be manually onboarded by sales staff and sent an invite to join through an org created for them. -- Your app only functions if users are part of an org, and you want to create the org for them during onboarding. -- You need an "admin account" with access to all orgs in your app, which can be achieved by creating orgs on users' behalf instead of allowing them to create their own. - -With the recommended setup, you can avoid unexpected rate limits, billing issues, and poor user experience. - -## Recommended Flow - -The recommended approach to ensuring that all users are in an organization is to implement an [onboarding flow](/docs/guides/add-onboarding-flow) in which it's required to create an organization before the user is able to access the application. You can use tools like the [`` component](/docs/components/organization/create-organization) to allow the user to create and name their own organization, or you can use Clerk's [Backend API](/docs/reference/backend-api/tag/Organizations#operation/CreateOrganization) or one of our backend SDKs like the [JS Backend SDK](/docs/references/backend/organization/create-organization) to create an organization on the user's behalf and name it as you'd like. - -If you'd like to have the your onboarding flow involve the user being invited to join your app via an email, you can use Clerk's [invitation functionality](/docs/users/invitations) to accomplish this. So the overall flow would look as such: - -- User receives an invitation to join your application -- Upon clicking the invitation, user registers their account and enters the onboarding flow -- User creates an organization as part of the onboarding flow, and is able to invite colleagues if relevant -- You now have a user that can access your application and is guaranteed to be in an organization - -If you'd also like to enable users to join an existing organization that matches their email domain if one exists, as an alternative to creating a new organization, you can use Clerk's [verified domains](/docs/organizations/verified-domains) feature to accomplish this. - -## You'd like admin access to all organizations in your app - -The easiest way to grant someone on your team admin access to all organizations in your app is to add them as a member to organization on clerk.com. Through Clerk's dashboard, you can see all of the organizations for each of your apps, and take administrative actions, such as adding or removing members, renaming, or deleting an organization. - -If for some reason this is not an option, you can use Clerk's [Backend API](/docs/reference/backend-api) or one of our backend SDKs like the [JS Backend SDK](/docs/references/backend/overview), alongside [roles and permissions](/docs/organizations/roles-permissions) to create a custom admin dashboard through which authorized users can can take adminstrative actions for organizations. - -## Not recommended: using an admin account to create organizations for users - -Although it may seem like a reasonable option, we strongly recommend against using a single admin account to create organizations on the behalf of users. Generally, this is because it can create unexpectedly high costs due to the way that organizations are billed. Let's walk through an example to see why. - -Imagine that you have an admin account that is configured to create organizations on a user's behalf during onboarding, then send an invitation to the user to join the organization. When the user accepts the invitation, their organization has an unneccessary extra admin account in it, and additionally at that point, the organization has two monthly active users (MAUs), which make it a active organization. All [Clerk plans](https://clerk.com/pricing) come with 100 active organizations included for free, but over that limit, organizations are billed at $1/month/org. This means that for every user that is created in your app, they have an active organization automatically, because of the fact that the admin account is also in the organization. This tends to result in much higher costs than if users' organizations are created without an admin account included. Additionally, it's generally a nicer user experience for users not to have extra admin accounts in their organizations. - -If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, please reach out to us at [support@clerk.com](mailto:support@clerk.com) and we'll be happy to help think through a suitable solution. diff --git a/docs/manifest.json b/docs/manifest.json index 71afa21beb..465bb97bbb 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -136,8 +136,8 @@ "href": "/docs/guides/custom-types" }, { - "title": "Creating Organizations on Users' Behalf", - "href": "/docs/guides/creating-orgs-for-users" + "title": "Create organizations on behalf of users", + "href": "/docs/guides/create-orgs-for-users" } ] ] From acedb2e986e051b09673b756611810875e44782c Mon Sep 17 00:00:00 2001 From: Jeff Escalante Date: Wed, 13 Nov 2024 17:03:59 -0500 Subject: [PATCH 5/8] move under organizations nav space --- docs/manifest.json | 8 ++++---- docs/{guides => organizations}/create-orgs-for-users.mdx | 0 2 files changed, 4 insertions(+), 4 deletions(-) rename docs/{guides => organizations}/create-orgs-for-users.mdx (100%) diff --git a/docs/manifest.json b/docs/manifest.json index 465bb97bbb..fd6526572b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -134,10 +134,6 @@ { "title": "Override Clerk interfaces with custom types", "href": "/docs/guides/custom-types" - }, - { - "title": "Create organizations on behalf of users", - "href": "/docs/guides/create-orgs-for-users" } ] ] @@ -619,6 +615,10 @@ { "title": "Organization workspaces", "href": "/docs/organizations/organization-workspaces" + }, + { + "title": "Create organizations on behalf of users", + "href": "/docs/guides/create-orgs-for-users" } ] ] diff --git a/docs/guides/create-orgs-for-users.mdx b/docs/organizations/create-orgs-for-users.mdx similarity index 100% rename from docs/guides/create-orgs-for-users.mdx rename to docs/organizations/create-orgs-for-users.mdx From 2616690da08a7a729b4ecdec7d54e854f41df188 Mon Sep 17 00:00:00 2001 From: Jeff Escalante Date: Wed, 13 Nov 2024 17:06:49 -0500 Subject: [PATCH 6/8] fix linter --- docs/organizations/create-orgs-for-users.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/organizations/create-orgs-for-users.mdx b/docs/organizations/create-orgs-for-users.mdx index 341ad3b3db..b6dbf51f87 100644 --- a/docs/organizations/create-orgs-for-users.mdx +++ b/docs/organizations/create-orgs-for-users.mdx @@ -36,4 +36,4 @@ If you have an architecture scenario that isn't covered here or feel that it's c The simplest way to grant someone on your team access to all orgs in your app is to add them as a member to your [organization workspace](/docs/organizations/organization-workspaces) in the Clerk Dashboard. Members of your organization workspace, also known as collaborators, can view all of the orgs for each of your apps and perform administrative actions, such as adding or removing members, renaming an org, or deleting an org. -If this isn't an option, you can use the [Backend API](/docs/reference/backend-api) or a backend SDK, such as the [JS Backend SDK](/docs/references/backend/overview), along with [roles and permissions](/docs/organizations/roles-permissions) to create a custom admin dashboard where authorized users can take adminstrative actions for orgs. \ No newline at end of file +If this isn't an option, you can use the [Backend API](/docs/reference/backend-api) or a backend SDK, such as the [JS Backend SDK](/docs/references/backend/overview), along with [roles and permissions](/docs/organizations/roles-permissions) to create a custom admin dashboard where authorized users can take adminstrative actions for orgs. From eb19c0f6055359fd3b58b377f3cceb99fc6f964c Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Thu, 14 Nov 2024 15:39:36 -0500 Subject: [PATCH 7/8] small copy updates --- docs/organizations/create-orgs-for-users.mdx | 26 +++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/organizations/create-orgs-for-users.mdx b/docs/organizations/create-orgs-for-users.mdx index b6dbf51f87..e2d627e510 100644 --- a/docs/organizations/create-orgs-for-users.mdx +++ b/docs/organizations/create-orgs-for-users.mdx @@ -3,22 +3,22 @@ title: Create organizations on behalf of users description: Learn how to architect your application to create organizations on users' behalf without running into rate limits and billing issues. --- -In some cases, you may want the onboarding for your app to include the creation of an organization on the user's behalf. This could be for a number of reasons, such as: +In some cases, you may want the onboarding process for your app to include creating an organization on the user's behalf. This could be beneficial for several reasons, such as: -- You would like for users to your application to be manually onboarded by sales staff and sent an invite to join via an organization created for them. -- Your application only makes sense if the user is part of an organization, and you want to create the organization on the user's behalf as part of the onboarding process. -- You would like to have an "admin account" that has access to all organizations across your application, and can achieve this easily by creating an organization for the user with an admin account, rather than allowing the user to create their own organization. +- You would like your users to be manually onboarded by sales staff, who send an invite to join via an organization created for them. +- Your app only makes sense if the user is part of an organization, so you want to create the organization on their behalf as part of onboarding. +- You would like to have an 'admin account' that has access to all organizations across your app and can achieve this by creating an organization for the user with an admin account, rather than allowing the user to create their own organization. -If this sounds like it fits your use case, this guide will walk you through how to architect your application without running into unexpected rate limits or billing issues, which can be a common problem when creating organizations on behalf of users. +If this aligns with your use case, this guide will walk you through architecting your application to avoid unexpected rate limits or billing issues, which can be a common problem when creating organizations on behalf of users. ## Recommended: require users to create orgs during onboarding -The recommended approach to ensure that all users are in an organization is to implement an [onboarding flow](/docs/guides/add-onboarding-flow) in which it's required to create an organization before the user is able to access the app. You can use tools like the [`` component](/docs/components/organization/create-organization) to allow the user to create and name their own organization, or you can use the [Backend API](/docs/reference/backend-api/tag/Organizations#operation/CreateOrganization) or a backend SDK like the [JS Backend SDK](/docs/references/backend/organization/create-organization) to create an organization on the user's behalf. +The recommended approach is to implement an [onboarding flow](/docs/guides/add-onboarding-flow) in which it's required to create an organization before the user is able to access the app. You can use tools like the [`` component](/docs/components/organization/create-organization) to allow the user to create and name their own organization, or you can use the [backend API](/docs/reference/backend-api/tag/Organizations#operation/CreateOrganization) or a backend SDK, such as the [JS Backend SDK](/docs/references/backend/organization/create-organization), to create an organization on the user's behalf. If you'd like to have the onboarding flow include inviting users via email, use the [invitation feature](/docs/users/invitations). The flow would look like this: -- User receives an invitation to join your app via email. -- User clicks the invitation link, registers an account, and enters the onboarding flow. +- User receives an invitation via email to join your app. +- User visits the invitation link, registers an account, and enters the onboarding flow. - User creates an organization as part of the onboarding flow, and can invite other users if needed. - The user can now access your app and is part of an org. @@ -26,14 +26,16 @@ If you'd like to enable users to join an existing org that matches their email d ## Not recommended: use an admin account to create organizations for users -Although it may seem like a reasonable option, it's strongly recommended not to use a single admin account to create organizations on the behalf of users. Generally, this is because it can create unexpectedly high costs due to the way that organizations are billed. Let's walk through an example to see why. +Although it may seem like a reasonable option, it's strongly recommended not to use a single admin account to create organizations on the behalf of users. Generally, this is because it can create **unexpectedly high costs** due to [the way that organizations are billed](/docs/organizations/overview#monthly-active-organization-mao). -Imagine that you have an admin account that is configured to create organizations on a user's behalf during onboarding, then sends an invitation to the user to join the organization. When the user accepts the invitation, their organization has an unneccessary extra admin account in it, and additionally at that point, the organization has two monthly active users (MAUs), which makes it a active organization. All [Clerk plans](https://clerk.com/pricing) come with 100 active organizations included for free, but over that limit, organizations are billed at $1 per month per org. In this case, for every user that is created in your app, they have an active organization automatically, because of the fact that the admin account is also in the organization. This tends to result in much higher costs than if users' organizations are created without an admin account included, since orgs with only one active user are not billable. Additionally, it's generally a nicer experience for users not to have extra admin accounts in their organizations. +Let's walk through an example to see why. -If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, reach out to us at [support@clerk.com](mailto:support@clerk.com) and we'll be happy to help think through a suitable solution. +Imagine you have an admin account configured to create organizations on a user's behalf during onboarding and then send an invitation to the user to join the organization. When the user accepts the invitation, the organization will have their account plus the admin account in it. At that point, the organization has two monthly active users (MAUs), which makes it a **billable** organization. All [Clerk plans](https://clerk.com/pricing) come with 100 active organizations included for free, but over that limit, organizations are billed at $1 per month. In this case, for every user that is created in your app, they have an active organization automatically, because of the fact that the admin account is also in the organization. This tends to result in much higher costs than if users' organizations are created without an admin account included, since orgs with only one active user are not billable. Additionally, it's generally a nicer experience for users not to have extra admin accounts in their organizations. + +If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, reach out to [support@clerk.com](mailto:support@clerk.com) for help thinking through a suitable solution. ## Grant a user access to all orgs The simplest way to grant someone on your team access to all orgs in your app is to add them as a member to your [organization workspace](/docs/organizations/organization-workspaces) in the Clerk Dashboard. Members of your organization workspace, also known as collaborators, can view all of the orgs for each of your apps and perform administrative actions, such as adding or removing members, renaming an org, or deleting an org. -If this isn't an option, you can use the [Backend API](/docs/reference/backend-api) or a backend SDK, such as the [JS Backend SDK](/docs/references/backend/overview), along with [roles and permissions](/docs/organizations/roles-permissions) to create a custom admin dashboard where authorized users can take adminstrative actions for orgs. +If this isn't an option, you can use the [backend API](/docs/reference/backend-api) or a backend SDK, such as the [JS Backend SDK](/docs/references/backend/overview), along with [roles and permissions](/docs/organizations/roles-permissions) to create a custom admin dashboard where authorized users can take adminstrative actions for orgs. From 976af9ae5c0ed32da361af47d398679fbd210972 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Fri, 15 Nov 2024 17:06:30 -0500 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: victoria --- docs/organizations/create-orgs-for-users.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/organizations/create-orgs-for-users.mdx b/docs/organizations/create-orgs-for-users.mdx index e2d627e510..60f31735d5 100644 --- a/docs/organizations/create-orgs-for-users.mdx +++ b/docs/organizations/create-orgs-for-users.mdx @@ -5,11 +5,11 @@ description: Learn how to architect your application to create organizations on In some cases, you may want the onboarding process for your app to include creating an organization on the user's behalf. This could be beneficial for several reasons, such as: -- You would like your users to be manually onboarded by sales staff, who send an invite to join via an organization created for them. +- You'd like your users to be manually onboarded by sales staff who will send invites to join via an organization created for them. - Your app only makes sense if the user is part of an organization, so you want to create the organization on their behalf as part of onboarding. -- You would like to have an 'admin account' that has access to all organizations across your app and can achieve this by creating an organization for the user with an admin account, rather than allowing the user to create their own organization. +- You'd like to have an "admin account" that has access to all organizations across your app and can achieve this by creating an organization for the user with an admin account, rather than allowing the user to create their own organization. -If this aligns with your use case, this guide will walk you through architecting your application to avoid unexpected rate limits or billing issues, which can be a common problem when creating organizations on behalf of users. +If this aligns with your use case, this guide will walk you through architecting your app to avoid unexpected rate limits or billing issues, which can be a common problem when creating organizations on behalf of users. ## Recommended: require users to create orgs during onboarding @@ -30,9 +30,9 @@ Although it may seem like a reasonable option, it's strongly recommended not to Let's walk through an example to see why. -Imagine you have an admin account configured to create organizations on a user's behalf during onboarding and then send an invitation to the user to join the organization. When the user accepts the invitation, the organization will have their account plus the admin account in it. At that point, the organization has two monthly active users (MAUs), which makes it a **billable** organization. All [Clerk plans](https://clerk.com/pricing) come with 100 active organizations included for free, but over that limit, organizations are billed at $1 per month. In this case, for every user that is created in your app, they have an active organization automatically, because of the fact that the admin account is also in the organization. This tends to result in much higher costs than if users' organizations are created without an admin account included, since orgs with only one active user are not billable. Additionally, it's generally a nicer experience for users not to have extra admin accounts in their organizations. +Imagine you have an admin account configured to create organizations on a user's behalf during onboarding and then sends an invitation to the user to join the organization. When the user accepts the invitation, the organization will have their account plus the admin account in it. At that point, the organization has two monthly active users (MAUs), which makes it a **billable** organization. All [Clerk plans](https://clerk.com/pricing) come with 100 active organizations included for free, but over that limit, organizations are billed at $1 per month. In this case, for every user that is created in your app, they have an active organization automatically, because of the fact that the admin account is also in the organization. This tends to result in much higher costs than if users' organizations are created without an admin account included, since orgs with only one active user are not billable. Additionally, it's generally a nicer experience for users not to have extra admin accounts in their organizations. -If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, reach out to [support@clerk.com](mailto:support@clerk.com) for help thinking through a suitable solution. +If you have an architecture scenario that isn't covered here or feel that it's critical to create organizations using an admin account, contact [support@clerk.com](mailto:support@clerk.com) for help. ## Grant a user access to all orgs