docs: clarify MTO tenant API permission-to-property mapping and role access

- Add detailed permission-to-property mapping showing which properties
  are returned for each permission level
- Document that Directory.Read.All also grants full read access to
  multitenant organization tenant resources (delegated or application)
- Clarify that ReadBasic.All only returns displayName and tenantId,
  and only active tenants
- Expand RBAC role documentation to specify that Security Reader and
  Global Reader can only read basic tenant info
- Add guidance on which role is needed for full property access
- Updated for both v1.0 and beta API references

Addresses IcM 31000000597799

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: srinivaspadala-msft

api-reference/beta/api/multitenantorganization-list-tenants.md

@@ -5,7 +5,7 @@ author: "rolyon"
 ms.localizationpriority: medium
 ms.subservice: "entra-sign-in"
 doc_type: apiPageType
-ms.date: 04/05/2024
+ms.date: 05/14/2026
 ---
 
 # List multiTenantOrganizationMembers
@@ -23,7 +23,11 @@ Choose the permission or permissions marked as least privileged for this API. Us
 <!-- { "blockType": "permissions", "name": "multitenantorganization_list_tenants" } -->
 [!INCLUDE [permissions-table](../includes/permissions/multitenantorganization-list-tenants-permissions.md)]
 
-If called with MultiTenantOrganization.Read.All or MultiTenantOrganization.ReadWrite.All permissions, this API returns both active and pending tenants. If called with MultiTenantOrganization.ReadBasic.All permission, the caller can only read the **displayName** and **tenantId** properties.
+The properties returned depend on the permission granted:
+
+- **MultiTenantOrganization.ReadBasic.All** (delegated): Returns only the **displayName** and **tenantId** properties. Only active tenants are returned.
+- **MultiTenantOrganization.Read.All** or **Directory.Read.All** (delegated or application): Returns all properties, including **addedDateTime**, **joinedDateTime**, **addedByTenantId**, **role**, **state**, and **transitionDetails**. Both active and pending tenants are returned.
+- **MultiTenantOrganization.ReadWrite.All** (delegated or application): Same access as MultiTenantOrganization.Read.All.
 
 [!INCLUDE [rbac-multitenantorganization-apis-read](../includes/rbac-for-apis/rbac-multitenantorganization-apis-read.md)]
 

api-reference/beta/includes/rbac-for-apis/rbac-multitenantorganization-apis-read.md

@@ -5,5 +5,7 @@ ms.topic: include
 
 > [!IMPORTANT]
 > For delegated access using work or school accounts, the signed-in user must be assigned a supported [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) or a custom role that grants the permissions required for this operation. This operation supports the following built-in roles, which provide only the least privilege necessary:
-> - Security Reader
-> - Global Reader
+> - **Security Reader** — Can read basic tenant information (**displayName** and **tenantId** only).
+> - **Global Reader** — Can read basic tenant information (**displayName** and **tenantId** only).
+>
+> To read all properties (including **role**, **state**, **addedByTenantId**, **addedDateTime**, **joinedDateTime**, and **transitionDetails**), the signed-in user must be assigned a role that grants the `MultiTenantOrganization.Read.All` or `MultiTenantOrganization.ReadWrite.All` permission, such as the **Global Administrator** role.

api-reference/v1.0/api/multitenantorganization-list-tenants.md

@@ -5,7 +5,7 @@ author: "rolyon"
 ms.localizationpriority: medium
 ms.subservice: "entra-sign-in"
 doc_type: apiPageType
-ms.date: 06/21/2024
+ms.date: 05/14/2026
 ---
 
 # List multiTenantOrganizationMembers
@@ -21,7 +21,11 @@ Choose the permission or permissions marked as least privileged for this API. Us
 <!-- { "blockType": "permissions", "name": "multitenantorganization_list_tenants" } -->
 [!INCLUDE [permissions-table](../includes/permissions/multitenantorganization-list-tenants-permissions.md)]
 
-If called with MultiTenantOrganization.Read.All or MultiTenantOrganization.ReadWrite.All permissions, this API returns both active and pending tenants. If called with MultiTenantOrganization.ReadBasic.All permission, the caller can only read the **displayName** and **tenantId** properties.
+The properties returned depend on the permission granted:
+
+- **MultiTenantOrganization.ReadBasic.All** (delegated): Returns only the **displayName** and **tenantId** properties. Only active tenants are returned.
+- **MultiTenantOrganization.Read.All** or **Directory.Read.All** (delegated or application): Returns all properties, including **addedDateTime**, **joinedDateTime**, **addedByTenantId**, **role**, **state**, and **transitionDetails**. Both active and pending tenants are returned.
+- **MultiTenantOrganization.ReadWrite.All** (delegated or application): Same access as MultiTenantOrganization.Read.All.
 
 [!INCLUDE [rbac-multitenantorganization-apis-read](../includes/rbac-for-apis/rbac-multitenantorganization-apis-read.md)]
 

api-reference/v1.0/includes/rbac-for-apis/rbac-multitenantorganization-apis-read.md

@@ -5,5 +5,7 @@ ms.topic: include
 
 > [!IMPORTANT]
 > For delegated access using work or school accounts, the signed-in user must be assigned a supported [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) or a custom role that grants the permissions required for this operation. This operation supports the following built-in roles, which provide only the least privilege necessary:
-> - Security Reader
-> - Global Reader
+> - **Security Reader** — Can read basic tenant information (**displayName** and **tenantId** only).
+> - **Global Reader** — Can read basic tenant information (**displayName** and **tenantId** only).
+>
+> To read all properties (including **role**, **state**, **addedByTenantId**, **addedDateTime**, **joinedDateTime**, and **transitionDetails**), the signed-in user must be assigned a role that grants the `MultiTenantOrganization.Read.All` or `MultiTenantOrganization.ReadWrite.All` permission, such as the **Global Administrator** role.