Merge pull request #28455 from microsoftgraph/author-api-docs-rbac-handling

author-api-docs: Add handling for Entra admin roles

Author: FaithOmbongi

.github/prompts/author-api-docs/common.md

@@ -407,6 +407,7 @@ Fully qualify any type (including enum types) that is defined in a subnamespace
 **Permissions:**
 - Must start with the standard boilerplate text
 - Must include link to a permissions table
+- **(Optional) RBAC include:** If the documentation plan or author specifies required Entra admin roles, add an RBAC include statement immediately after the permissions table include. See [RBAC for APIs include file templates](../../../templates/rbac-for-apis-include.md) for file conventions, naming, and content templates.
 
 **HTTP request:**
 - Use relative URLs (e.g., `/users` not `https://graph.microsoft.com/beta/users`)
@@ -691,6 +692,7 @@ After processing all files in a documentation session, verify cross-file consist
 2. **API file ↔ resource link:** Every API file's description should link back to its parent resource, and that resource file should exist
 3. **Enum references ↔ definitions:** Every enum type referenced in Properties tables should be defined in the appropriate enums file, parent resource, or separate topic
 4. **Permissions files:** Every permissions include reference in API files should have a corresponding file in the `includes/permissions/` folder
+5. **RBAC files:** If any API file has an RBAC include reference, verify the corresponding file exists in `includes/rbac-for-apis/`
 5. **JSON representation ↔ Properties table:** Properties listed in the JSON representation section should match the Properties table
 6. **Polymorphic collections:** If a Documentation Plan flagged polymorphic types, verify: (a) no operation files were created using derived type names, (b) all shared operation files use the base type name, (c) base type resource page has the Methods table (including base-type-only operations for concrete bases), (d) derived type resource pages have a `## Methods` section with only a polymorphic note (no Methods table — the table lives only on the base type page), (e) `@odata.type` guidance is included in POST/PATCH request body sections
 

.github/prompts/author-api-docs/ga.md

@@ -111,6 +111,7 @@ The shortest route is to **copy the relevant beta topics** from the `api-referen
    - Copy resource files from `api-reference\beta\resources\` to `api-reference\v1.0\resources\`
    - Copy API method files from `api-reference\beta\api\` to `api-reference\v1.0\api\`
    - Copy permission include files from `api-reference\beta\includes\permissions\` to `api-reference\v1.0\includes\permissions\`
+   - Copy RBAC include files (if they exist) from `api-reference\beta\includes\rbac-for-apis\` to `api-reference\v1.0\includes\rbac-for-apis\`
 
 ### Step 2: Update copied files for v1.0
 
@@ -300,6 +301,10 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 **For permission include files:**
 - [ ] Files copied from beta\includes\permissions to v1.0\includes\permissions
 
+**For RBAC include files (if applicable):**
+- [ ] Files copied from beta\includes\rbac-for-apis to v1.0\includes\rbac-for-apis
+- [ ] If new RBAC info provided but no beta file exists, file created using [RBAC templates](../../../templates/rbac-for-apis-include.md)
+
 **For concept topics (if applicable):**
 - [ ] Code examples updated from /beta to /v1.0
 - [ ] All "(preview)" references removed from content
@@ -319,6 +324,7 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 - [ ] All resource files promoted and updated
 - [ ] All API method files promoted and updated
 - [ ] All permission files copied
+- [ ] All RBAC include files copied (if applicable)
 - [ ] All concept topics updated if applicable
 - [ ] All TOC entries updated
 - [ ] Changelog and What's new updated

.github/prompts/author-api-docs/public-preview.md

@@ -308,7 +308,14 @@ When API changes involve adding new properties or relationships to an existing r
      - `api-reference/v1.0/includes/permissions/`
    - Do not make any changes to these permissions files
 
-4. **HTTP request section:**
+4. **RBAC include (optional — only when admin role info is provided):**
+   - If the documentation plan or author specifies required Entra admin roles for the API:
+     - Create the RBAC include file using the templates in [RBAC for APIs include file templates](../../../templates/rbac-for-apis-include.md)
+     - Place in `api-reference/{version}/includes/rbac-for-apis/`
+     - Add the include statement after the permissions table include, before `## HTTP request`
+   - If no admin role info is provided, skip this step
+
+5. **HTTP request section:**
    - Confirm the endpoint matches the endpoints in the API.md
    - Correct where you can
    - **For actions/functions in subnamespaces:** See [namespace qualification rules](common.md#namespace-qualification) for fully qualifying actions/functions
@@ -559,6 +566,7 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 - [ ] Description links back to parent resource (e.g. `Get a [user](../resources/user.md).`)
 - [ ] Permissions section unchanged
 - [ ] Permissions include file copied to correct includes folder
+- [ ] RBAC include file created and added if admin role info was provided
 - [ ] HTTP request: Endpoints confirmed against API.md
 - [ ] HTTP request: Endpoints match example URL in Examples section except relative URL
 - [ ] HTTP request: Actions/functions in subnamespaces are fully qualified

templates/changelog-patterns.md

@@ -1,3 +1,4 @@
+<!-- -This template file is consumed by the /authorAPIDocs prompt -->
 # Manual Changelog Authoring Guide
 
 This guide covers how to manually create changelog entries for changes that don't trigger automatic generation (e.g., throttling updates, query capability changes, page size limit changes).
@@ -21,7 +22,7 @@ Each changelog entry must be part of a "ChangeList" array with the following req
 
 | Property | Description | Example Values |
 |----------|-------------|----------------|
-| **Id** | GUID identifier. Use the same GUID for all related changes in a release. | "6ebc1737-3f93-4ef1-a9e7-cafa03262cf8" |
+| **Id** | GUID identifier. Use the same GUID for all related objects in a ChangeList. | "6ebc1737-3f93-4ef1-a9e7-cafa03262cf8" |
 | **ApiChange** | The type of Microsoft Graph API element being changed. | "Resource", "Property", "Relationship", "Method", "Enumeration", "Member", "Parameter", "Header", "Permission" |
 | **ChangedApiName** | The name of the specific API element that changed. | "user", "displayName", "manager", "delta", "status", "active", "id", "Authorization", "User.Read.All" |
 | **ChangeType** | The nature of the change. | "Addition", "Change", "Deletion", "Deprecation" |
@@ -34,6 +35,7 @@ These properties apply to the entire changelog record (not individual ChangeList
 
 | Property | Description | Default Value | Possible Values |
 |----------|-------------|---------------|-----------------|
+| **Id** | GUID identifier for the changelog record. Use the same GUID as the ChangeList Id. | (None - must specify) | Same GUID as ChangeList Id |
 | **Cloud** | The cloud environment where the change is available. | "prd" | "prd" (production) |
 | **Version** | The API version where the change is available. | "v1.0" | "v1.0", "beta" |
 | **CreatedDateTime** | UTC timestamp when the changelog entry was created. Use PowerShell: `(Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffffffZ")` | Current UTC datetime | "2025-11-17T17:38:10.4694969Z" (ISO 8601/RFC 3339 format with fractional seconds) |

templates/rbac-for-apis-include.md

@@ -0,0 +1,77 @@
+<!-- -This template file is consumed by the /authorAPIDocs prompt -->
+# RBAC for APIs include file templates
+
+Use these templates when creating RBAC (role-based access control) include files for API operation topics. These files inform callers which Microsoft Entra admin roles are required in delegated scenarios, in addition to Microsoft Graph permissions.
+
+## File conventions
+
+- **Location:** `api-reference/{version}/includes/rbac-for-apis/`
+- **Naming:** `rbac-{feature-area}-apis-{operation}.md` — for example, `rbac-identity-provider-apis.md`, `rbac-access-reviews-apis-read.md`
+- **Placement in API file:** Immediately after the permissions table include statement, before the `## HTTP request` section
+
+### Include syntax in API operation files
+
+```markdown
+[!INCLUDE [rbac-{descriptive-label}](../includes/rbac-for-apis/{filename}.md)]
+```
+
+---
+
+## Template A — Single least privileged role
+
+Use when one Entra admin role is the least privileged role for the operation.
+
+```markdown
+---
+author: {github-username}
+ms.topic: include
+---
+
+> [!IMPORTANT]
+> In delegated scenarios with 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 with a supported role permission. *{Role Name}* is the least privileged role supported for this operation.
+```
+
+### Example (Template A)
+
+```markdown
+---
+author: janedoe
+ms.topic: include
+---
+
+> [!IMPORTANT]
+> In delegated scenarios with 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 with a supported role permission. *External Identity Provider Administrator* is the least privileged role supported for this operation.
+```
+
+---
+
+## Template B — Multiple least privileged roles
+
+Use when two or more Entra admin roles are supported for the operation, listed from least to most privileged.
+
+```markdown
+---
+author: {github-username}
+ms.topic: include
+---
+
+> [!IMPORTANT]
+> In delegated scenarios with 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 with a supported role permission. The following least privileged roles are supported for this operation.
+> - {Role Name 1}
+> - {Role Name 2}
+> - {Role Name 3}
+```
+
+### Example (Template B)
+
+```markdown
+---
+author: janedoe
+ms.topic: include
+---
+
+> [!IMPORTANT]
+> In delegated scenarios with 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 with a supported role permission. The following least privileged roles are supported for this operation.
+> - Cloud Application Administrator
+> - Application Administrator
+```