Merge pull request #1281 from logto-io/guamian-doc

fix: update copy and images

Author: fleuraly

docs/end-user-flows/organization-experience/create-organization.mdx

@@ -26,12 +26,15 @@ Create an [organization template](/authorization/organization-template) to batch
 
 ### Create via Logto Management API \{#create-via-logto-management-api}
 
-The Console is great for manual setup, but most apps let end users self‑serve—create and manage organizations directly in your app. To do that, implement these features with the Logto Management API.
+The console is great for manual setup, but most apps let end users self‑serve—create and manage organizations directly in your app. To do that, implement these features with the Logto Management API.
 
 :::note
 
-If you’re new to the Logto Management API, read these first:
+If you’re new to the Logto Management API or haven't read the basic intro of using Logto Management API for organization experience, read these first:
 
+<Url href="/end-user-flows/organization-experience/setup-app-service-with-management-api">
+  Set up your app service with the Logto Management API
+</Url>
 <Url href="/concepts/core-service/#management-api">Management API</Url>
 <Url href="/integrate-logto/interact-with-management-api">Interact with Management API</Url>
 

docs/end-user-flows/organization-experience/get-user-info.mdx

@@ -14,7 +14,7 @@ This is usually used in the user profile page where users need to show their org
 
 There are two ways to get user info within an organization.
 
-### 1. Decode the ID token \{#1-decode-the-id-token}
+### Decode the ID token \{#decode-the-id-token}
 
 The ID token is a standard JWT that contains user profile information and organization‑related claims. Call the SDK method `decodeIdToken()` to get a JSON object like this:
 
@@ -55,6 +55,6 @@ logtoClient.signIn({
 
 If the session is still valid, the `signIn` call will redirect back to your app without requiring credentials. From the user’s perspective, the app simply refreshes and a new ID token is issued behind the scenes.
 
-### 2. Fetch user info from the `/oidc/me` endpoint \{#2-fetch-user-info-from-the-oidc-me-endpoint}
+### Fetch user info from the `/oidc/me` endpoint \{#fetch-user-info-from-the-oidc-me-endpoint}
 
 You can also request `/oidc/me` to get real‑time user info in the organization context. Call the SDK method `fetchUserInfo()`.

docs/end-user-flows/organization-experience/invite-organization-members.mdx

@@ -4,7 +4,7 @@ sidebar_position: 6
 
 # Invite organization members
 
-In multi‑organization applications, a common requirement is inviting members to an organization. This guide walks through the steps and technical details to implement this feature.
+In multi‑tenancy applications, a common requirement is inviting members to an organization. This guide walks through the steps and technical details to implement this feature.
 
 ## Flow overview \{#flow-overview}
 
@@ -87,10 +87,15 @@ There’s a set of invitation‑related Management APIs in the organizations fea
 - `POST /api/organization-invitations`: Create an organization invitation with an assigned organization role.
 - `POST /api/one-time-tokens`: Create a one‑time token for the invitee to authenticate when they accept the invitation. [Learn more](/end-user-flows/one-time-token)
 - `POST /api/organization-invitations/{id}/message`: Send the organization invitation to the invitee via email.
-  Note: The payload supports a `link` property so you can compose your own invitation link based on the invitation ID. For example:
 
-  ```json
-  {
-    "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email"
-  }
-  ```
+:::note
+
+The payload supports a `link` property so you can compose your own invitation link based on the invitation ID. For example:
+
+:::
+
+```json
+{
+  "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email"
+}
+```

docs/end-user-flows/organization-experience/join-the-organization.mdx

@@ -6,9 +6,11 @@ sidebar_position: 7
 
 ## Where to use it \{#where-to-use-it}
 
-The organization list typically appears during the user onboarding flow. For example, when an admin invites you to join a workspace.
+The organization list and joining flow usually appear during user onboarding.
+For example, when an admin invites someone to a workspace, but the user skips the email invitation and directly signs in or signs up in the app.
 
-From a product perspective, it can show up in two main places:
+In your product, you may want to add entry points for this flow.
+It can appear in two main places:
 
 - The **organization finder** during sign-in or sign-up
 

docs/end-user-flows/organization-experience/permission-and-resource-management.mdx

@@ -2,21 +2,26 @@
 sidebar_position: 8
 ---
 
-# Permission and resource management
+# Handle scope updates in organization tokens
 
-Use the organization as a resource and apply an organization template to protect it. For example, each organization has its own documents within a tenant. Only users with the right roles can edit or delete those documents.
+With the above setup, you can send invitations via email, and invitees can join the organization with the assigned role.
 
-See [Organization permissions](/authorization/organization-permissions) for details.
+Users with different organization roles will have different scopes (permissions) in their organization tokens. Both your client app and backend services should check these scopes to determine visible features and permitted actions.
 
-## Use organization role-based access control (RBAC) to manage user permissions \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions}
+As mentioned earlier, the organization template serves as a key access control layer to protect [organization permissions](/authorization/organization-permissions) or [organization-level APIs](/authorization/organization-level-api-resources). Be sure to review the authorization sections and choose the authorization model that best fits your product.
 
-With the above setup, you can send invitations via email, and invitees can join the organization with the assigned role.
+:::note
 
-Users with different organization roles will have different scopes (permissions) in their organization tokens. Both your client app and backend services should check these scopes to determine visible features and permitted actions.
+<Url href="/authorization/organization-permissions">Protect organization (non-API) permissions</Url>
+<Url href="/authorization/organization-level-api-resources">
+  Protect organization-level API resources
+</Url>
 
-## Handle scope updates in organization tokens \{#handle-scope-updates-in-organization-tokens}
+:::
+
+This chapter focuses on **permission management** and best practices for **handling scope changes and permissions** in Logto organization tokens.
 
-This section covers advanced topics about managing the organization template and authorization scenarios. If you’re not familiar with these concepts, read [Authorization](/authorization) and [Organization template](/authorization/organization-template) first.
+## Handle scope updates in organization tokens \{#handle-scope-updates-in-organization-tokens}
 
 Managing scope updates in organization tokens involves:
 

docs/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx

@@ -4,9 +4,10 @@ sidebar_position: 2
 
 # Set up your app service with the Logto Management API
 
-Use the Logto **Management API** to build custom **organization flows** in your app. Below are the basic setup steps for integrating the Management API. If you’re already familiar, you can skip ahead to the [tutorial](/integrate-logto/interact-with-management-api).
+Logto offers a powerful Management API that lets you create and customize your own organization flow inside your app.
+Understanding how it works is key to designing your custom setup. Below are the basic steps and outline to integrate the Management API to implement your organization experience.
 
-Once you’re familiar with the setup, you can explore additional APIs to tailor the rest of the flows to your business needs.
+If you already know the basics, you can skip ahead to the [tutorial](/integrate-logto/interact-with-management-api). Once you’re familiar with the setup, you can explore additional APIs to tailor the rest of the flows to your business needs.
 
 ## Establish a machine-to-machine connection \{#establish-a-machine-to-machine-connection}
 
@@ -31,7 +32,7 @@ curl \
 
 ## Protect your app server \{#protect-your-app-server}
 
-Because end users can perform certain organization operations self‑serve, add an authorization layer between the end user and your app server. The server should mediate every request, validate the user’s organization‑scoped token and required scopes, and only then use a server‑held M2M credential to invoke the Management API.
+Since end users can perform certain organization actions on their own, it’s important to add an authorization layer between the end user and your app server.\You can apply this layer globally or at the organization level, depending on which Logto Management API endpoints you use and how your product’s API is structured.The server should mediate every request, validate the user’s organization‑scoped token and required scopes, and only then use a server‑held M2M credential to invoke the Management API.
 
 When a user presents an organization token to request an action (for example, creating an organization), the server first validates the scopes in the token. If the token includes the necessary scope, such as `org:create`, authorize the request and call the Logto Management API via the M2M flow to create the organization.
 
@@ -71,10 +72,20 @@ This ensures that when calling `getOrganizationToken(organizationId)`, the clien
 
 For details on protecting organization‑level (non‑API) permissions, see the [full guide](/authorization/organization-permissions).
 
-### Mixing organization-level permissions and API-level permissions \{#mixing-organization-level-permissions-and-api-level-permissions}
+### Using API-level permissions \{#using-api-level-permissions}
 
 This applies when your API resources and permissions are registered globally, but roles are defined at the organization level (you can assign API‑level permissions to organization roles in the organization template).
 
 The implementation is the same as the previous section. Always provide the organization ID and call `getOrganizationToken(organizationId)` to fetch an organization token; otherwise, organization permissions won’t be included.
 
 For details on protecting organization‑level API permissions, see the [full guide](/authorization/organization-level-api-resources).
+
+### Using global RBAC
+
+In this case, you can use the Logto Management API to implement system-level access control.
+
+In a multi-tenant environment, a common pattern is to have a superuser or super admin role. For example, if you’re building a SaaS platform with Logto, you might want a superuser who can manage all client organizations directly within your own app, without needing to log in to the Logto Console.
+
+This superuser can perform higher-level actions, such as creating or deleting organizations in bulk, that require system, wide permissions beyond any single organization context. To enable this, register an API resource in Logto while levergaing the Logto Management API and use global RBAC to manage these permissions.
+
+For more details on integrating and managing access control for RBAC, see the full guide see the [full guide](/authorization/global-api-resources).