PIM Iteration 2 API Retirement on October 28, 2026: What You Need to Do Now

TL; DR

Microsoft will retire the Microsoft Entra Privileged Identity Management (PIM) Iteration 2 (beta) APIs on October 28, 2026. Any automation, scripts, or integrations using the /beta/privilegedAccess endpoints will stop working after this date.

If you manage privileged access using automation, you must migrate to Iteration 3 (Generally Available) APIs to avoid service disruption.

• The Break: Any script using /beta/privilegedAccess will fail.
• The Fix: Move to /v1.0/roleManagement/directory (Iteration 3).
• The Impact: This isn't just a URL change; it requires a new permission set and a shift in how you handle role assignments.

Background

The older Iteration 2 APIs were built on a "Provider" architecture (specifically the aadRoles and azureResources providers). While functional, they were inconsistent with the rest of Microsoft Graph.

Iteration 3 brings PIM into the Unified Role Management fold. This means PIM operations now look and act like standard Entra ID role assignments, providing better reliability and faster execution.

These APIs are now being fully replaced by Iteration 3 APIs, which are production-ready, more consistent, and aligned with the Microsoft Graph and Azure Resource Manager architecture.

Official Retirement Timeline

What Exactly Is Being Retired

The retirement specifically affects APIs under:

/beta/privilegedAccess

Affected API Segments

/beta/privilegedAccess/aadRoles/beta/privilegedAccess/azureResources

These endpoints were commonly used to manage:

• Microsoft Entra roles
• Azure resource roles
• Privileged assignments
• Eligibility schedules

Role Assignments/beta/privilegedAccess/aadRoles/roleAssignments/v1.0/roleManagement/directory/roleAssignmentsRole Definitions/beta/privilegedAccess/aadRoles/roleDefinitions/v1.0/roleManagement/directory/roleDefinitionsAssignment Requests/beta/privilegedAccess/aadRoles/roleAssignmentRequests/v1.0/roleManagement/directory/roleAssignmentScheduleRequestsEligible Assignments/beta/privilegedAccess/aadRoles/roleEligibilityRequests/v1.0/roleManagement/directory/roleEligibilityScheduleRequests

Real-World Impact

If your organization uses automation, the impact can be significant.

Examples of What Will Break

• PowerShell scripts activating admin roles
• Scheduled tasks managing role eligibility
• CI/CD pipelines granting temporary permissions
• Service principals managing privileged access
• Custom portals integrating with PIM

Typical symptoms after retirement:

HTTP 404

HTTP 410

Authorization errors or Empty responses

This is not a permissions issue . . .

the 403 / provider not supported error

the legacy permissions that now require admin consent

Request

GET https://graph.microsoft.com/beta/privilegedAccess

Result

The request fails with a 403 Forbidden error and an additional provider error message.

Screenshot: Deprecated Endpoint Call

What this shows

• The request targets /beta/privilegedAccess
• Required permissions are missing or unsupported
• The provider is no longer supported for Microsoft Graph

Why This Error Happens?

This error is not just a permission issue. It is an architectural change.

The PrivilegedAccess provider model used in Iteration 2 is being phased out and replaced by the Unified Role Management model in Iteration 3.

This means:

• The endpoint still exists in beta
• But the provider is no longer supported
• And eventually the endpoint will be removed entirely

After October 28, 2026, these calls will fail permanently.

Important Observation

All permissions show:

Admin consent required: Yes
Status: Unconsented

This is expected behavior because:

• These permissions belong to the deprecated Iteration 2 API model
• Many tenants are no longer granting consent
• New development should not use these permissions

Identifying "Breaking" Automation

In a regulated enterprise, you likely have these legacy calls hidden in:

• PowerShell Scripts: Used by Helpdesk to manually trigger role elevations.
• Service Principals: Automated "break-glass" or maintenance window assignments.
• Legacy Permissions: App Registrations using PrivilegedAccess.ReadWrite.AzureAD.

Critical Note: The legacy PrivilegedAccess.* permissions are being replaced. You must grant the newer RoleManagement.ReadWrite.Directory and PrivilegedAssignmentSchedule.ReadWrite.Directory permissions to your automation identities.

Migration Path Overview

To migrate, you must update two things: Your Code and Your App Permissions.

Endpoint Mapping

Direct Roles /beta/privilegedAccess/aadRoles /v1.0/roleManagement/directory Azure Resources /beta/privilegedAccess/azureResources /v1.0/roleManagement/cloudPC (or ARM APIs) Assignments .../roleAssignments .../roleAssignmentScheduleRequests

Permission Mapping

Stop using the "PrivilegedAccess" scopes. Switch your Service Principal or App Registration to:

• For Directory Roles: RoleManagement.ReadWrite.Directory
• For PIM Specifics: PrivilegedAssignmentSchedule.ReadWrite.Directory

Migration Path: Terraform (Recommended)

For regulated entities, moving PIM management into Terraform ensures a clear audit trail. Iteration 3 is fully supported by the AzureAD (Entra) and Microsoft Graph providers.

Example: Defining an Eligible Role Assignment

Instead of a beta API call, use the azuread_privileged_access_group_eligibility_schedule or the equivalent role assignment resource:

Terraform

# Iteration 3 Approach using Terraform
resource "azuread_privileged_access_group_eligibility_schedule" "admin_eligibility" {
  group_id             = azuread_group.privileged_group.id
  principal_id         = azuread_user.admin_user.object_id
  role_definition_id   = "f2ef1f12-3b3f-4ae0-bde6-ee2019ad5493" # Global Reader
  
  schedule {
    start_date = "2026-03-30T00:00:00Z"
    expiration {
      duration_days = 365
    }
  }
}

Migration Path: PowerShell (SDK)

If you must use scripts, use the Microsoft Graph PowerShell SDK (v2.x+), which defaults to the Iteration 3 logic.

PowerShell

# Migrating a Role Activation Request
$params = @{
    Action = "selfActivate"
    Justification = "Regulated Change Request #12345"
    RoleDefinitionId = "f2ef1f12-3b3f-4ae0-bde6-ee2019ad5493"
    DirectoryScopeId = "/"
    PrincipalId = "USER_GUID"
    ScheduleInfo = @{
        StartDateTime = [System.DateTime]::UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ")
        Expiration = @{
            Type = "afterDuration"
            Duration = "PT4H" # 4-hour window for compliance
        }
    }
}

New-MgRoleManagementDirectoryRoleAssignmentScheduleRequest -BodyParameter $params

Action Plan for Admins

1. Audit: Scan all ADO/GitHub/GitLab repositories for references to privilegedAccess/aadRoles.
2. Permission Update: Update App Registrations to include the Unified Role Management Microsoft Graph scopes.
3. Decommission: Disable legacy Service Principals once their Iteration 3 equivalents are verified.
4. Deadline: Ensure all migrations are complete before October 28, 2026.

Pro-Tip for Regulated Enterprises:

⚠️ Audit Warning: Security auditors may flag "Unconsented" or "Deprecated" permissions in your App Registrations. Removing these legacy PrivilegedAccess.* scopes is a key step in reducing your Entra ID attack surface.

If you're running a similar setup or have questions, reach out in the comments or on LinkedIn.

— Antonio | AboutCloud

arusso@aboutcloud.io