Merge pull request #198510 from MicrosoftDocs/main

5/17 AM Publishing

Author: v-alje

articles/active-directory/index.yml

@@ -110,8 +110,8 @@
     href: pim-troubleshoot.md
 - name: Reference
   items:
-  - name: Graph API  
-    href: /graph/api/resources/azure-ad-overview
+  - name: Microsoft Graph API  
+    href: /graph/api/resources/privilegedidentitymanagementv3-overview
   - name: Azure AD CLI    
     href: /cli/azure/ad
   - name:  Azure AD PowerShell for Graph

articles/active-directory/privileged-identity-management/TOC.yml

@@ -37,19 +37,19 @@ As a delegated approver, you'll receive an email notification when an Azure AD r
 
     In the **Requests for role activations** section, you'll see a list of requests pending your approval.
 
-## View pending requests using Graph API
+## View pending requests using Microsoft Graph API
 
 ### HTTP request
 
 ````HTTP
-GET https://graph.microsoft.com/beta/roleManagement/directory/roleAssignmentScheduleRequests/filterByCurrentUser(on='approver')?$filter=status eq 'PendingApproval' 
+GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests/filterByCurrentUser(on='approver')?$filter=status eq 'PendingApproval' 
 ````
 
 ### HTTP response
 
 ````HTTP
 { 
-    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(unifiedRoleAssignmentScheduleRequest)", 
+    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(unifiedRoleAssignmentScheduleRequest)", 
     "value": [ 
         { 
             "@odata.type": "#microsoft.graph.unifiedRoleAssignmentScheduleRequest", 
@@ -105,7 +105,7 @@ GET https://graph.microsoft.com/beta/roleManagement/directory/roleAssignmentSche
 
     ![Approve notification showing request was approved](./media/pim-resource-roles-approval-workflow/resources-approve-pane.png)
 
-## Approve pending requests using Graph API
+## Approve pending requests using Microsoft Graph API
 
 ### Get IDs for the steps that require approval
 

articles/active-directory/privileged-identity-management/azure-ad-pim-approval-workflow.md

@@ -22,7 +22,7 @@ You can perform Privileged Identity Management (PIM) tasks using the Microsoft G
 
 For requests and other details about PIM APIs, check out:
 
-- [PIM for Azure AD roles API reference](/graph/api/resources/unifiedroleeligibilityschedulerequest?view=graph-rest-beta&preserve-view=true)
+- [PIM for Azure AD roles API reference](/graph/api/resources/privilegedidentitymanagementv3-overview)
 - [PIM for Azure resource roles API reference](/rest/api/authorization/roleeligibilityschedulerequests)
 
 ## PIM API history
@@ -35,11 +35,11 @@ Under the /beta/privilegedRoles endpoint, Microsoft had a classic version of the
 
 ### Iteration 2 – Supports Azure AD roles and Azure resource roles
 
-Under the /beta/privilegedAccess endpoint, Microsoft supported both /aadRoles and /azureResources. This endpoint is still available in your tenant but Microsoft recommends against starting any new development with this API. This beta API will never be released to general availability and will be eventually deprecated.
+Under the `/beta/privilegedAccess` endpoint, Microsoft supported both `/aadRoles` and `/azureResources`. This endpoint is still available in your tenant but Microsoft recommends against starting any new development with this API. This beta API will never be released to general availability and will be eventually deprecated.
 
 ### Current iteration – Azure AD roles in Microsoft Graph and Azure resource roles in Azure Resource Manager
 
-Now in beta, Microsoft has the final iteration of the PIM API before we release the API to general availability. Based on customer feedback, the Azure AD PIM API is now under the unifiedRoleManagement set of API and the Azure Resource PIM API is now under the Azure Resource Manager role assignment API. These locations also provide a few additional benefits including:
+Currently in general availability, this is the final iteration of the PIM API. Based on customer feedback, the PIM API for managing Azure AD roles is now under the **unifiedRoleManagement** set of APIs and the Azure Resource PIM API is now under the Azure Resource Manager role assignment API. These locations also provide a few additional benefits including:
 
 - Alignment of the PIM API for regular role assignment API for both Azure AD roles and Azure Resource roles.
 - Reducing the need to call additional PIM API to onboard a resource, get a resource, or get role definition.
@@ -52,16 +52,13 @@ In the current iteration, there is no API support for PIM alerts and privileged
 
 ### Azure AD roles
 
-  To call the PIM Graph API for Azure AD roles, you will need at least one of the following permissions:
+To understand the permissions that you need to call the PIM Microsoft Graph API for Azure AD roles, see [Role management permissions](/graph/permissions-reference#role-management-permissions).
 
-- RoleManagement.ReadWrite.Directory
-- RoleManagement.Read.Directory
-
-  The easiest way to specify the required permissions is to use the Azure AD consent framework.
+The easiest way to specify the required permissions is to use the Azure AD consent framework.
 
 ### Azure resource roles
 
-  The PIM API for Azure resource roles is developed on top of the Azure Resource Manager framework. You will need to give consent to Azure Resource Management but won’t need any Graph API permission. You will also need to make sure the user or the service principal calling the API has at least the Owner or User Access Administrator role on the resource you are trying to administer.
+  The PIM API for Azure resource roles is developed on top of the Azure Resource Manager framework. You will need to give consent to Azure Resource Management but won’t need any Microsoft Graph API permission. You will also need to make sure the user or the service principal calling the API has at least the Owner or User Access Administrator role on the resource you are trying to administer.
 
 ## Calling PIM API with an app-only token
 
@@ -80,52 +77,59 @@ In the current iteration, there is no API support for PIM alerts and privileged
 
 PIM API consists of two categories that are consistent for both the API for Azure AD roles and Azure resource roles: assignment and activation API requests, and policy settings.
 
-### Assignment and activation API
+### Assignment and activation APIs
 
-To make eligible assignments, time-bound eligible/active assignments, and to activate assignments, PIM provides the following entities:
+To make eligible assignments, time-bound eligible or active assignments, and to activate eligible assignments, PIM provides the following resources:
 
-- RoleAssignmentSchedule
-- RoleEligibilitySchedule
-- RoleAssignmentScheduleInstance
-- RoleEligibilityScheduleInstance
-- RoleAssignmentScheduleRequest
-- RoleEligibilityScheduleRequest
+- [unifiedRoleAssignmentScheduleRequest](/graph/api/resources/unifiedroleassignmentschedulerequest)
+- [unifiedRoleEligibilityScheduleRequest](/graph/api/resources/unifiedroleeligibilityschedulerequest)
 
-These entities work alongside pre-existing roleDefinition and roleAssignment entities for both Azure AD roles and Azure roles to allow you to create end to end scenarios.
+These entities work alongside pre-existing **roleDefinition** and **roleAssignment** resources for both Azure AD roles and Azure roles to allow you to create end to end scenarios.
 
 - If you are trying to create or retrieve a persistent (active) role assignment that does not have a schedule (start or end time), you should avoid these PIM entities and focus on the read/write operations under the roleAssignment entity
 
-- To create an eligible assignment with or without an expiration time you can use the write operation on roleEligibilityScheduleRequest
+- To create an eligible assignment with or without an expiration time you can use the write operation on the [unifiedRoleEligibilityScheduleRequest](/graph/api/resources/unifiedroleeligibilityschedulerequest) resource
+
+- To create a persistent (active) assignment with a schedule (start or end time), you can use the write operation on the  [unifiedRoleAssignmentScheduleRequest](/graph/api/resources/unifiedroleassignmentschedulerequest) resource
+
+- To activate an eligible assignment, you should also use the [write operation on roleAssignmentScheduleRequest](/graph/api/rbacapplication-post-roleassignmentschedulerequests) with a `selfActivate` **action** property.
 
-- To create a persistent (active) assignment with a schedule (start or end time), you can use the write operation on roleAssignmentScheduleRequest  
+Each of the request objects would create the following read-only objects:
 
-- To activate an eligible assignment, you should also use the write operation on roleAssignmentScheduleRequest with a modified action parameter called selfActivate
+- [unifiedRoleAssignmentSchedule](/graph/api/resources/unifiedroleassignmentschedule)
+- [unifiedRoleEligibilitySchedule](/graph/api/resources/unifiedroleeligibilityschedule)
+- [unifiedRoleAssignmentScheduleInstance](/graph/api/resources/unifiedroleassignmentscheduleinstance)
+- [unifiedRoleEligibilityScheduleInstance](/graph/api/resources/unifiedroleeligibilityscheduleinstance)
 
-Each of the request objects would either create a roleAssignmentSchedule or a roleEligibilitySchedule object. These objects are read-only and show a schedule of all the current and future assignments.
+The **unifiedRoleAssignmentSchedule** and **unifiedRoleEligibilitySchedule** objects show a schedule of all the current and future assignments.
 
-When an eligible assignment is activated, the roleEligibilityScheduleInstance continues to exist. The roleAssignmentScheduleRequest for the activation would create a separate roleAssignmentSchedule and roleAssignmentScheduleInstance for that activated duration.
+When an eligible assignment is activated, the **unifiedRoleEligibilityScheduleInstance** continues to exist. The **unifiedRoleAssignmentScheduleRequest** for the activation would create a separate **unifiedRoleAssignmentSchedule** object and a **unifiedRoleAssignmentScheduleInstance** for that activated duration.
 
 The instance objects are the actual assignments that currently exist whether it is an eligible assignment or an active assignment. You should use the GET operation on the instance entity to retrieve a list of eligible assignments / active assignments to a role/user.
 
-### Policy setting API
+For more information about assignment and activation APIs, see [PIM API for managing role assignments and eligibilities](/graph/api/resources/privilegedidentitymanagementv3-overview#pim-api-for-managing-role-assignment).
+
+### Policy settings APIs
+
+To manage the settings of Azure AD roles, we provide the following entities:
 
-To manage the setting, we provide the following entities:
+- [unifiedroleManagementPolicy](/graph/api/resources/unifiedrolemanagementpolicy)
+- [unifiedroleManagementPolicyAssignment](/graph/api/resources/unifiedrolemanagementpolicyassignment)
 
-- roleManagementPolicy
-- roleManagementPolicyAssignment
+The [unifiedroleManagementPolicy](/graph/api/resources/unifiedrolemanagementpolicy) resource through it's **rules** relationship defines the rules or settings of the Azure AD role. For example, whether MFA/approval is required, whether and who to send the email notifications to, or whether permanent assignments are allowed or not. The [unifiedroleManagementPolicyAssignment](/graph/api/resources/unifiedrolemanagementpolicyassignment) object attaches the policy to a specific role.
 
-The *role management policy* defines the setting of the rule. For example, whether MFA/approval is required, whether and who to send the email notifications to, or whether permanent assignments are allowed or not. The *policy assignment* attaches the policy to a specific role.
+Use the APIs supported by these resources retrieve role management policy assignments for all Azure AD role or filter the list by a **roleDefinitionId**, and then update the rules or settings in the policy associated with the Azure AD role.
 
-Use this API is to get a list of all the roleManagementPolicyAssignments, filter it by the roleDefinitionID you want to modify, and then update the policy associated with the policyAssignment.
+For more information about the policy settings APIs, see [role settings and PIM](/graph/api/resources/privilegedidentitymanagementv3-overview#role-settings-and-pim).
 
 ## Relationship between PIM entities and role assignment entities
 
-The only link between the PIM entity and the role assignment entity for persistent (active) assignment for either Azure AD roles or Azure roles is the roleAssignmentScheduleInstance. There is a one-to-one mapping between the two entities. That mapping means roleAssignment and roleAssignmentScheduleInstance would both include:  
+The only link between the PIM entity and the role assignment entity for persistent (active) assignment for either Azure AD roles or Azure roles is the unifiedRoleAssignmentScheduleInstance. There is a one-to-one mapping between the two entities. That mapping means roleAssignment and unifiedRoleAssignmentScheduleInstance would both include:  
 
 - Persistent (active) assignments made outside of PIM
 - Persistent (active) assignments with a schedule made inside PIM
 - Activated eligible assignments
 
 ## Next steps
 
-- [Azure AD Privileged Identity Management API reference](/graph/api/resources/privilegedidentitymanagement-root?view=graph-rest-beta&preserve-view=true)
+- [Azure AD Privileged Identity Management API reference](/graph/api/resources/privilegedidentitymanagementv3-overview)