refactor: refactor the organization experience docs (#1278)

* refactor: refactor the organization experience docs

* chore: sync i18n translation and rewrite heading IDs

* refactor: update index file and add a missing image

Author: charIeszhao

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

@@ -9,16 +9,77 @@ import OrganizationIcon from '@site/src/assets/organization.svg';
 
 # Organization experience
 
-[Organization](/organizations) experience refers to the user interfaces and flows used by your business clients and their employees, particularly in [multi-tenant applications](https://auth.wiki/multi-tenancy). Logto provides several guides to help you quickly integrate this experience into your app using the Logto Management API.
+The [organization](/organizations) experience is the set of UIs and flows your business customers and their employees use—especially in [multi-tenant applications](https://auth.wiki/multi-tenancy). This guide shows how to integrate it into your app using the Logto Management API.
+
+This section helps you design the **organization experience** for your end users—for example:
+
+1. Admins can create their own organizations.
+2. Admins can manage organization members.
+3. Admins can invite members to join their organizations.
+4. and more.
 
 <center>
   <img src="/img/assets/organization-experience.webp" width="100%" alt="Organization experience" />
 </center>
 
-## Features for organization experience \{#features-for-organization-experience}
+## Understand the authentication flow \{#understand-the-authentication-flow}
+
+```mermaid
+sequenceDiagram
+  actor User
+  participant Frontend
+  participant Backend
+  participant Logto
+
+  User->>Frontend: Request to create organization
+  Frontend->>Backend: POST /organizations
+  Backend->>Logto: POST /api/organizations
+  Logto-->>Backend: Organization created
+  Backend->>Logto: POST /api/organizations/{id}/users
+  Logto-->>Backend: User added to organization
+  Backend-->>Frontend: Success response
+  Frontend-->>User: Show success message
+```
+
+To integrate with the Logto Management API, first understand the basic authentication flow. It has two key requirements:
+
+### Protect your backend API \{#protect-your-backend-api}
+
+- Frontend calls to your backend API require authentication.
+- Protect API endpoints by validating the user's Logto access token.
+- Ensure only authenticated users can access your services.
+
+### Access the Logto Management API \{#access-the-logto-management-api}
+
+- Your backend service securely calls the Logto Management API.
+- Follow the [Interact with Management API](/integrate-logto/interact-with-management-api) guide for setup.
+- Use machine-to-machine authentication to obtain access credentials.
+
+The next few chapters explain how to set up the Logto Management API and walk through common use cases for building your organization experience.
+
+## Organization experience features \{#features-for-organization-experience}
 
 <DocCardList
   items={[
+    {
+      type: 'link',
+      label: 'Define organization management features',
+      href: '/end-user-flows/organization-experience/organization-management',
+      description: 'Design your own multi-tenant app with organization roles and permissions.',
+      customProps: {
+        icon: <OrganizationIcon />,
+      },
+    },
+    {
+      type: 'link',
+      label: 'Set up your app service with the Logto Management API',
+      href: '/end-user-flows/organization-experience/setup-app-service-with-management-api',
+      description:
+        'Securely connect your backend to Logto Management API using machine-to-machine authentication.',
+      customProps: {
+        icon: <GearIcon />,
+      },
+    },
     {
       type: 'link',
       label: 'Create organization',
@@ -31,27 +92,54 @@ import OrganizationIcon from '@site/src/assets/organization.svg';
     },
     {
       type: 'link',
-      label: 'Invite members to organization',
-      href: '/end-user-flows/organization-experience/invite-organization-members',
-      description:
-        'Use Logto Management API to let organization admins invite members to their organizations.',
+      label: 'Get user info within an organization',
+      href: '/end-user-flows/organization-experience/get-user-info',
+      description: 'Fetch user information within an organization.',
       customProps: {
         icon: <OrganizationIcon />,
       },
     },
     {
       type: 'link',
-      label: 'Organization management',
-      href: '/end-user-flows/organization-experience/organization-management',
-      description:
-        'Use Logto Management API to let organization admins manage their members inside the organization.',
+      label: 'Organization switcher',
+      href: '/end-user-flows/organization-experience/organization-switcher',
+      description: 'Implement organization switching in your app.',
+      customProps: {
+        icon: <GearIcon />,
+      },
+    },
+    {
+      type: 'link',
+      label: 'Invite organization members',
+      href: '/end-user-flows/organization-experience/invite-organization-members',
+      description: 'Use Logto Management API to implement organization invitations.',
+      customProps: {
+        icon: <GearIcon />,
+      },
+    },
+    {
+      type: 'link',
+      label: 'Join the organization',
+      href: '/end-user-flows/organization-experience/join-the-organization',
+      description: 'Implement the joining organization flows in your app.',
+      customProps: {
+        icon: <GearIcon />,
+      },
+    },
+    {
+      type: 'link',
+      label: 'Permission and resource management',
+      href: '/end-user-flows/organization-experience/permission-and-resource-management',
+      description: 'Manage permissions and resources within an organization',
       customProps: {
         icon: <GearIcon />,
       },
     },
   ]}
 />
 
+For a detailed explanation of organization definitions, member concepts, and organization templates, see [Understand how organizations work](/organizations/understand-how-organizations-work).
+
 ## Related resources \{#related-resources}
 
 <Url href="https://blog.logto.io/build-multi-tenant-saas-application">

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

@@ -1,37 +1,43 @@
 ---
-sidebar_position: 1
+sidebar_position: 3
 ---
 
 # Create organization
 
-Imagine you are building a [multi-tenant app](https://auth.wiki/multi-tenancy) (e.g., multi-tenant SaaS app) that servers numerous customers, and each customer owns a dedicated tenant. When a new customer arrives, they create a new account, as well as a new tenant for their own business.
+Imagine you’re building a [multi-tenant app](https://auth.wiki/multi-tenancy) (e.g., a multi-tenant SaaS app) that serves many customers, and each customer owns a dedicated tenant.
 
-Just like how you registered your [Logto Cloud](https://cloud.logto.io/) account and have your own Logto tenant. You can implement the very same architecture in your app as well, using Logto's "[organization](/organizations)" feature.
+Organizations are typically created when:
 
-## Create your organizations \{#create-your-organizations}
+1. New customers sign up and create both an account and a tenant for their business.
+2. Existing users can create a new organization from within the app.
+
+<img src="/img/assets/new-account-creates-org.png" alt="New account creates organization" />
+<img src="/img/assets/existing-user-creates-org.png" alt="Existing user creates organization" />
+
+## Implement organization creation \{#implement-organization-creation}
 
 There are two ways to create organizations for your app.
 
 ### Create via Logto Console \{#create-via-logto-console}
 
-Manually create your organizations through Logto Console UI. Go to <CloudLink to="/organizations">Console > Organizations</CloudLink> to create organization, assign members and roles, and customize organization sign-in experience UI.
+Manually create organizations in the Logto Console UI. Go to <CloudLink to="/organizations">Console > Organizations</CloudLink> to create organizations, assign members and roles, and customize the organization sign‑in experience.
 
-Create an "[organization template](/authorization/organization-template)" if you want to batch create similar organizations that share the same role and permission settings.
+Create an [organization template](/authorization/organization-template) to batch‑create similar organizations that share the same roles and permissions.
 
 ### Create via Logto Management API \{#create-via-logto-management-api}
 
-Clicking buttons on the Console UI works great, but we really want to have the end-users self-serve and create organizations, manage the organizations themselves In **YOUR App**. Thus, you’ll have to implement these features in your app, with the help of 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 are not familiar with Logto Management API, please make sure you read these docs first.
+If you’re new to the Logto Management API, read these first:
 
 <Url href="/concepts/core-service/#management-api">Management API</Url>
 <Url href="/integrate-logto/interact-with-management-api">Interact with Management API</Url>
 
 :::
 
-Assuming you have already connected your API backend server to Logto Management API endpoint through the Machine-to-Machine (M2M) mechanism, and acquired the M2M access token.
+Assume your backend is connected to the Logto Management API via the machine‑to‑machine (M2M) mechanism, and you’ve obtained an M2M access token.
 
 Create an organization with Management API ([API references](https://openapi.logto.io/operation/operation-createorganization)):
 
@@ -43,30 +49,24 @@ curl \
  -d '{"tenantId":"string","name":"string","description":"string","customData":{},"isMfaRequired":false,"branding":{"logoUrl":"string","darkLogoUrl":"string","favicon":"string","darkFavicon":"string"},"createdAt":1234567890}'
 ```
 
-Response example (201)
-
-```json
-{
-  "tenantId": "string",
-  "id": "string",
-  "name": "string",
-  "description": "string",
-  "customData": {},
-  "isMfaRequired": false,
-  "branding": {
-    "logoUrl": "string",
-    "darkLogoUrl": "string",
-    "favicon": "string",
-    "darkFavicon": "string"
-  },
-  "createdAt": 1234567890
-}
+Then add the user as a member of the organization ([API reference](https://openapi.logto.io/operation/operation-addorganizationusers)):
+
+```bash
+curl \
+ -X POST https://[tenant_id].logto.app/api/organizations/{id}/users \
+ -H "Authorization: Bearer $M2M_ACCESS_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"userIds":["string"]}'
 ```
 
-Next, you can implement your own API for your app. So when your users perform the "create organization" action in your app, you can validate the request by checking their permissions, and then call Logto Management API to do the rest of the job.
+Optionally, assign specific organization roles to the user ([API reference](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)).
+
+Check the [full API specs](https://openapi.logto.io/group/endpoint-organizations) for more details.
+
+Wrap these calls in your own API layer. When users perform the “create organization” action in your app, validate the request by checking their permissions, then call the Logto Management API to complete the operation.
 
-## Validating organization token in user request \{#validating-organization-token-in-user-request}
+## Validate the organization token in user requests \{#validating-organization-token-in-user-request}
 
-In your app, when users perform actions in the context of an organization, they need to use the organization token instead of the regular access token. The organization token is a special kind of [JWT](https://auth.wiki/jwt) that contains organization permissions. And just like any JWT [access tokens](https://auth.wiki/access-token), you can decode the token claims and verify the "scope" claim for permission check.
+In your app, when users perform actions in the context of an organization, they must use an organization token instead of a regular access token. The organization token is a [JWT](https://auth.wiki/jwt) that contains organization permissions. Like any [access token](https://auth.wiki/access-token), you can decode the claims and verify the "scope" claim to enforce permissions.
 
-See <Url href="/authorization">Authorization</Url> for more details about authorization scenarios and how to validate organization tokens.
+See <Url href="/authorization">Authorization</Url> for more on authorization scenarios and how to validate organization tokens.

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

@@ -0,0 +1,60 @@
+---
+sidebar_position: 4
+---
+
+# Get user info within an organization
+
+## Where to use it \{#where-to-use-it}
+
+This is usually used in the user profile page where users need to show their organization information.
+
+<img src="/img/assets/user-info-page.png" alt="Organization user info" />
+
+## How to implement it \{#how-to-implement-it}
+
+There are two ways to get user info within an organization.
+
+### 1. Decode the ID token \{#1-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:
+
+```json
+{
+  "sub": "aauqbb63vg4s",
+  "name": "John Doe",
+  "picture": "https://example.com/johndoe.png",
+  "email": "johndoe@example.com",
+  // ...
+  "organizations": [
+    "organization-id-1",
+    "organization-id-2",
+    "organization-id-3"
+    // ...
+  ],
+  "organization_roles": [
+    "organization-id-1:admin",
+    "organization-id-2:member",
+    "organization-id-3:viewer"
+    // ...
+  ],
+  "aud": "admin-console"
+  // ...
+}
+```
+
+However, the ID token is only issued during authentication and may become stale if the user profile changes afterward.
+For the most up‑to‑date info, use the second approach below, or call `clearAllTokens()` and re‑initiate an authentication flow to get a fresh ID token.
+
+```ts
+await logtoClient.clearAllTokens();
+logtoClient.signIn({
+  redirectUri: 'https://your-app.com/callback',
+  prompt: 'consent',
+});
+```
+
+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}
+
+You can also request `/oidc/me` to get real‑time user info in the organization context. Call the SDK method `fetchUserInfo()`.