docs: add opaque token and organization information (#1321)

Author: fleuraly

docs/concepts/opaque-token.mdx

@@ -54,3 +54,14 @@ curl --location \
 ```
 
 Remember to replace `[tenant-id]` with your tenant ID.
+
+## Opaque token and organizations \{#opaque-token-and-organizations}
+
+Opaque tokens can be used to retrieve organization membership information via the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). When you request the `urn:logto:scope:organizations` scope, the userinfo endpoint will return the user's organization-related claims, such as `organizations` (organization IDs) and `organization_data`.
+
+However, **opaque tokens cannot be used as organization tokens**. Organization tokens are always issued in JWT format because:
+
+1. Organization tokens contain organization-specific claims (like `organization_id` and scoped permissions) that need to be validated by resource servers.
+2. The JWT format allows resource servers to verify the token and extract organization context without additional API calls.
+
+To obtain an organization token, you need to use the [refresh token flow](/authorization/organization-permissions#refresh-token-flow) or [client credentials flow](/authorization/organization-permissions#client-credentials-flow) with organization parameters.

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

@@ -58,3 +58,9 @@ If the session is still valid, the `signIn` call will redirect back to your app
 ### 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()`.
+
+:::tip[Opaque token support]
+If you are using an [opaque token](/concepts/opaque-token) (issued when no API resource is specified), you can still retrieve organization membership information through the userinfo endpoint. When you request the `urn:logto:scope:organizations` scope, the response will include `organizations` and other organization-related claims.
+
+Note that opaque tokens cannot be used as organization tokens for accessing organization-specific resources. See [Opaque token and organizations](/concepts/opaque-token#opaque-token-and-organizations) for more details.
+:::

docs/quick-starts/fragments/_scope-claim-list.md

@@ -66,6 +66,10 @@ Please refer to the [OpenID Connect Core 1.0](https://openid.net/specs/openid-co
 | organizations     | `string[]` | The organization IDs the user belongs to  | No              |
 | organization_data | `object[]` | The organization data the user belongs to | Yes             |
 
+:::note
+These organization claims can also be retrieved via the userinfo endpoint when using an [opaque token](/concepts/opaque-token). However, opaque tokens cannot be used as organization tokens for accessing organization-specific resources. See [Opaque token and organizations](/concepts/opaque-token#opaque-token-and-organizations) for more details.
+:::
+
 **`urn:logto:scope:organization_roles`**
 
 | Claim name         | Type       | Description                                                                                   | Needs userinfo? |