docs: init organization docs

docs/docs/recipes/organizations/README.mdx

@@ -0,0 +1,33 @@
+---
+sidebar_position: 7.1
+---
+
+import Availability from '@components/Availability';
+
+# 🏢 Organizations (Multi-tenancy)
+
+<Availability cloud="comingSoon" oss={{ major: 1, minor: 12 }} />
+
+Organization is particularly effective in business-to-business (B2B) apps. In addtion to individual consumers, business clients can also consist of teams, organizations, or entire companies. Logto introduces the entity of an organization as a foundational element for authentication and authorization in B2B products, for example, SaaS.
+
+Even if your product is not B2B, organization can still be useful for collaboration features, such as sharing resources with other users.
+
+With this fundamental element, you can build the must-have features for multi-tenancy apps, such as:
+
+- A product that can be used by multiple organizations.
+- Organization member provision on an invitation or just-in-time basis.
+- Access controls that defined by roles assigned to members within an organization.
+- Single Sign-On (SSO) authentication experience.
+
+The term "organization" is also used in other forms, such as "workspace", "team", "company", etc. In Logto, we use "organization" as the generic term to represent the concept of multi-tenancy.
+
+## Before we start
+
+Hold on, you may heard of some products use the term "multi-tenancy" to represent the identity isolation: each tenant has its own set of users, permissions, and data.
+
+It may be counterintuitive, but in fact, "multi-tenancy" indicates the contrary: multiple tenants are sharing resources in a single instance. For example, in Notion (a popular collaboration tool):
+
+- You can create and join multiple workspaces with one account, instead of sign up for each workspace with different accounts.
+- For each workspace, Notion defines a **same set** of access levels: "Worksapce owner" and "member", while you may expect different access levels for different workspaces.
+
+For more information, see our [blog post about tenancy models](https://blog.logto.io/tenancy-models/).

docs/docs/recipes/organizations/configure-organizations.mdx

@@ -0,0 +1,67 @@
+---
+sidebar_position: 2
+---
+
+# Configure organizations
+
+## Configure via Console
+
+We'll go through the process of configuring the organizations feature via Logto Console (https://cloud.logto.io/).
+
+### Start setting up your organization feature
+
+When you activate the organization feature, you'll be guided through essential settings like setting up organization permissions, roles, and creating your first organization. You will gain a clearer understanding of how organizations function within Logto. After the initial setup, you can add members, assign roles within the organization, or refine your organization template.
+
+In the organization list, you can create an organization and configure its details. On the organization details page, you can:
+
+1. Modify the organization's name and description.
+2. Add members and assign them organization roles.
+3. Remove a user's membership in the organization.
+4. Delete the organization.
+5. Access a guide to understand more about organizations and the organization template.
+
+### Adding members and assigning organization roles
+
+Users can hold one or more roles. When adding members to an organization, you have the option to assign roles to multiple users at once. If you leave this assignment blank, the added users will not receive any roles.
+
+In the user management section, on the user detail page, you can see which organizations the users belong to and what organization roles they have.
+
+### Configure organization template
+
+The organization template consists of permissions and roles, which can be edited freely; any changes will affect users with those roles across all organizations.
+
+## Configure via Management API
+
+Everything you can do in Console can also be done through Management API. This includes, but not limited to:
+
+1. Create, delete, or edit an organization.
+2. Add users to the organization.
+3. Remove users from the organization.
+4. Manage organization template:
+
+- Add, delete, or edit organization roles.
+- Add, delete, or edit organization permissions.
+
+5. Assign or remove user's organization roles.
+
+For a complete list of capabilities, please refer to our [API references](https://openapi.logto.io/group/endpoint-organizations).
+
+### Example: Develop a platform or interface that enables your clients to manage identities within their organization
+
+A common scenario for your product involves having both admins and members. They will manage resources and identities at different levels.
+
+| Role   | Permissions                                                     |
+| ------ | --------------------------------------------------------------- |
+| Admin  | Able to invite users to and remove users from the organization. |
+| Member | Only able to invite users to the organization.                  |
+
+So we can define the following organization template:
+
+- Organization permissions: `invite:users`, `remove:users`.
+- Organization roles:
+  - `admin` with permissions `invite:users` and `remove:users`.
+  - `member` with permission `remove:users`.
+
+You can use `POST /organization-scopes` in Management API to create the organization permissions first, then use `POST /organization-roles` to create roles.
+
+After organization template is set, you may also create two APIs in your service that call Management API under the hood for inviting and removing users in a specific organization. The APIs in your service should check organizaiton acces token to ensure the user has the right access. See Organization RBAC for details.

docs/docs/recipes/organizations/impact-on-end-users.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+# Impact on end-user sign-in experience
+
+Currently, there's no impact to the end-user sign-in experience since Logto decouples authentication and authorization. For exmaple, Enterprise SSO (single sign-on) is based on email domains, not organizations.
+
+As the user signs in, they can get the access to all organizations with membership. For detailed information, please refer to Organization RBAC.
+
+We may add advanced features for organizations that change the sign-in experience in the future. Please

docs/docs/recipes/organizations/understand-how-it-works.mdx

@@ -0,0 +1,83 @@
+---
+sidebar_position: 1
+---
+
+import organizationExmaple from './assets/organization-example.webp';
+import organizationMembers from './assets/organization-members.webp';
+import organizationPermission from './assets/organization-permission.webp';
+import organizationRole from './assets/organization-role.webp';
+
+# Understand how organizations work
+
+## Organization
+
+Organization consists of a group of users (identities). It can represent the teams, business customers, and partner companies who can access to your application.
+
+The introduction of an organization as an entity is important, as it not only groups users but also provides a context for tenant isolation in multi-tenant apps. To learn more about tenant isolation, check out our multi-tenant application best practice.
+
+## Organization member
+
+In Logto, a user who has the membership of an organization is referred to as an organization member (i.e. member) within that organization's context.
+
+<img alt="Organization member" src={organizationMembers} width={720} />
+
+## Organization permission
+
+Organization permission refers to the authorization to perform an action in the context of organization. An organization permission should be represented as a meaningful string, also serving as the name and unique identifier.
+
+For example, `edit:resource`.
+
+<img alt="Organization permission" src={organizationPermission} width={720} />
+
+Organization permissions are not meaningful without the context of an organization. For example, `edit:resource` in the context of organization `org1` is different from `edit:resource` in the context of organization `org2`.
+
+## Organization role
+
+Organization role is a grouping of organization permissions that can be assigned to users. The permissions must come from the predefined organization permissions.
+
+<img alt="Organization role" src={organizationRole} width={720} />
+
+Organization roles are not meaningful without the context of an organization. For example, `admin` in the context of organization `org1` is different from `admin` in the context of organization `org2`.
+
+## Organization template
+
+Organization template refers to a collection of organization permissions and roles that apply to every organization.
+
+Think of a typical collaboration app, and they naturally share the same access control “template” that defines access levels and what users can do in the organization. We call it "organization template” in Logto.
+
+Let’s take an example to understand how everything connects:
+
+**John**, **Sarah** are in different organizations with different roles in the context of different organizations.
+
+<img
+  alt="Organization example with template"
+  src={organizationExmaple}
+  style={{
+    /* The image has no white padding, manually add some. */
+    padding: '12px 24px',
+    background: 'white',
+  }}
+/>
+
+From this diagram, here are some info you need to know:
+
+1. **John** is affiliated with two organizations, using the email "[email protected]" as his unique identifier. He holds the position of `admin` in `Organization A` and is a `guest` in `Organization B`.
+2. **Sarah** is associated with a single organization and uses the email "[email protected]" as her unique identifier. She is the `admin` of `Organization B`.
+3. The roles of `Admin`, `Member`, and `Guest` are designated within organizations and these roles are consistent across various organizations.
+4. Additional roles can be created within the organization template settings. These newly created roles will be applied and shared across all organizations.
+
+:::note
+💡 In Logto, the organization template serves as an access control model tailored for organizations. While it's based on the RBAC (role-based access control) model, it differs from the API resource RBAC feature.
+
+When you need to design roles and permissions specific to an organization, use the organization template (organization RBAC).
+
+You can use both organization RBAC and API resource RBAC in Logto, allowing a more robust approach to meet your specific business and product requirements. For details on API resource RBAC, refer to [this section](https://docs.logto.io/docs/recipes/rbac/).
+:::
+
+## Managing identities in organizations
+
+The organization template in Logto is intended to secure isolated resources at the organizational level, ensuring users in different roles have the right access.
+
+You may notice that the organization template doesn’t define identity management, such as which role can invite or remove users in an organization, since it varis for different products and business needs.
+
+While we are working on a productized solution for organization idenitty management, you can use the Management API to tailor a solution. For detailed guidance on using the management API for this, please refer to this section.

src/components/Availability/index.module.scss

@@ -0,0 +1,10 @@
+.availability {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 12px 0;
+
+  img {
+    border-radius: 0;
+  }
+}

src/components/Availability/index.tsx

@@ -0,0 +1,57 @@
+import styles from './index.module.scss';
+
+/** A type that represents a semantic version for new features (major.minor). */
+type MinorVersion = {
+  major: number;
+  minor: number;
+};
+
+/** A type that represents the feature is coming soon. */
+type ComingSoon = 'comingSoon';
+
+type Props = {
+  /** Whether the feature is available in Logto Cloud. */
+  cloud: boolean | ComingSoon;
+  /**
+   * Whether the feature is available in Logto OSS. If it is a `MinorVersion`,
+   * it means the feature is available in Logto OSS since the specified version.
+   */
+  oss: boolean | ComingSoon | MinorVersion;
+};
+
+const getDisplayText = (status: boolean | ComingSoon | MinorVersion) => {
+  if (status === 'comingSoon') {
+    return 'coming soon-blue';
+  }
+
+  if (typeof status === 'boolean') {
+    return status ? 'Yes-green' : 'N/A-gray';
+  }
+
+  return `v${status.major}.${status.minor}-green`;
+};
+
+/**
+ * A component that shows the availability of the feature in Logto Cloud and Logto OSS.
+ * Open source availability can have a version number.
+ */
+const Availability = ({ cloud, oss }: Props) => {
+  return (
+    <div className={styles.availability}>
+      {cloud && (
+        <img
+          alt="Cloud availability"
+          src={`https://img.shields.io/badge/Cloud-${getDisplayText(cloud)}`}
+        />
+      )}
+      {oss && (
+        <img
+          alt="OSS availability"
+          src={`https://img.shields.io/badge/OSS-${getDisplayText(oss)}`}
+        />
+      )}
+    </div>
+  );
+};
+
+export default Availability;