Edit

Privileged Identity Management iteration 2 APIs

  • Article

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Caution

The Privileged Identity Management (PIM) API for Azure resources and Microsoft Entra roles iteration 2 will be deprecated soon. Use the new Azure REST PIM API for Azure resources and PIM API for Microsoft Entra roles iteration 3. To migrate, see the migration guidance.

Privileged Identity Management (PIM) is a service that enables you to manage, control, and monitor access to important resources in your organization. This scope includes access to resources in Microsoft Entra ID, Azure resources, and other Microsoft services like Microsoft 365 or Microsoft Intune.

There have been several iterations of the PIM API over the past few years. This iteration is the second iteration (here referred to as iteration 2) and it's succeeded by PIM iteration 3. For more information about the history of the PIM API, see PIM API history.

Microsoft Graph provides the following PIM iteration 2 APIs to manage Microsoft Entra roles and Azure resource roles. We recommend that you migrate from PIM iteration 2 API to PIM iteration 3 API.

Migrate from PIM iteration 2 APIs to PIM iteration 3 APIs

Migrate to the Azure Resource Manager (ARM) PIM API for Azure resource roles

The PIM iteration 3 API to manage Azure resources is now available through the Azure Resource Manager (ARM) REST API. Use this guidance to migrate your existing APIs to the new Azure Resource Manager (ARM) APIs.

The following table describes how the new ARM APIs map to the existing APIs.

Operation Microsoft Graph API (iteration 2) ARM API (iteration 3)
Register a resource Register ARM doesn't require resources to be explicitly registered or onboarded to be managed. You can perform operations by directly using the resource scope.
List role definitions List Role definitions Role Definitions - List
Create role assignment requests Create governanceRoleAssignmentRequest Use Role Eligibility Schedule Requests - Create to create eligible role assignments

Use Role Assignment Schedule Requests - Create to create active role assignments
List role assignments List governanceRoleAssignments Use Role Eligibility Schedule Instances - List to get eligible role assignments

Use Role Assignment Schedule Instances - List to get active role assignments
Manage Role Settings List governanceRoleSettings
Update governanceRoleSetting		 Manage policies through ARM