Privileged Identity Management iteration 2 APIs
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.
- APIs for Microsoft Entra roles
- APIs for Azure resources
Migrate from PIM iteration 2 APIs to PIM iteration 3 APIs
Migrate to the Azure Resource Manager PIM APIs for Azure resource roles
The PIM iteration 3 API to manage Azure resources is now available through the Azure Resource Manager REST APIs. Use this guidance to migrate your existing APIs to the new Azure Resource Manager APIs.
The following table describes how the Azure Resource Manager PIM APIs map to the existing Microsoft Graph APIs.
| Operation | Microsoft Graph API (iteration 2) | Azure Resource Manager API (iteration 3) |
|---|---|---|
| Register a resource | Register | Resource Manager 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 Azure Resource Manager |