Privileged Identity Management (deprecated)

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 AD roles is deprecated and stopped returning data on May 31, 2021. Use the role management API for privileged identity management and see the migration guidance below.

The Privileged Identity Management (PIM) API for Azure resources will be deprecated soon. Use the new Azure REST PIM API for Azure resources. To migrate, see the migration guidance below.

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 Azure AD, 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 PIM v2) and it's succeeded by PIM v3. For more information about the history of the PIM API, see PIM API history.

Microsoft Graph provides the following PIM v2 APIs to manage Azure AD roles and Azure resource roles. We recommend that you migrate from PIM v2 to PIM v3.

• APIs for Azure AD roles (deprecated)
• APIs for Azure resources

Migrate from PIM v2 to PIM v3 APIs

Migrate to PIM v3 API for Azure AD roles (role management APIs)

The PIM API for Azure AD roles has been retired and stopped returning data on May 31, 2021. Use this guidance to migrate your existing APIs to the new role management API for privileged identity management.

Operation	PIM v2 API	Role management APIs (PIM v3)
List role definitions	List privilegedRoles	List unifiedRoleDefinitions
Manage Role Settings	Get privilegedRoleSettings Update privilegedRoleSettings	Manage policies
Create role assignment requests	Create privilegedRoleAssignmentRequest	Use Create unifiedRoleEligibilityScheduleRequest to create eligible role assignments Use Create unifiedRoleAssignmentScheduleRequest to create active role assignments
List role assignments	List privilegedRoleAssignments	Use List unifiedRoleEligibilityScheduleInstances to get eligible role assignments Use List unifiedRoleAssignmentScheduleInstances to get active role assignments

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

The PIM v3 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 (PIM v2)	ARM API (PIM v3)
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