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).

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
+```