Anthropic-Cybersecurity-Skills/skills/implementing-privileged-identity-management-with-azure/references/api-reference.md

Azure AD PIM Microsoft Graph API Reference

Authentication

import msal

app = msal.ConfidentialClientApplication(
    client_id="<app-id>",
    authority="https://login.microsoftonline.com/<tenant-id>",
    client_credential="<client-secret>"
)
token = app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])

Required API Permissions

Permission	Type	Description
RoleManagement.ReadWrite.Directory	Application	Manage role assignments
RoleEligibilitySchedule.ReadWrite.Directory	Application	Manage eligible assignments
RoleAssignmentSchedule.ReadWrite.Directory	Application	Manage active assignments
AuditLog.Read.All	Application	Read PIM audit logs
Policy.Read.All	Application	Read role management policies

PIM API Endpoints

List Eligible Role Assignments

GET /roleManagement/directory/roleEligibilityScheduleInstances

Create Eligible Assignment

POST /roleManagement/directory/roleEligibilityScheduleRequests
{
  "action": "adminAssign",
  "justification": "Business need for temporary access",
  "roleDefinitionId": "<role-id>",
  "directoryScopeId": "/",
  "principalId": "<user-object-id>",
  "scheduleInfo": {
    "startDateTime": "2025-03-01T00:00:00Z",
    "expiration": {
      "type": "afterDuration",
      "duration": "PT8H"
    }
  }
}

Activate Eligible Role (JIT)

POST /roleManagement/directory/roleAssignmentScheduleRequests
{
  "action": "selfActivate",
  "justification": "Need Global Admin for security investigation",
  "roleDefinitionId": "<role-id>",
  "directoryScopeId": "/",
  "principalId": "me",
  "scheduleInfo": {
    "startDateTime": "2025-03-01T12:00:00Z",
    "expiration": {
      "type": "afterDuration",
      "duration": "PT1H"
    }
  }
}

List Active Role Assignments

GET /roleManagement/directory/roleAssignmentScheduleInstances

List Role Definitions

GET /roleManagement/directory/roleDefinitions

Query PIM Audit Logs

GET /auditLogs/directoryAudits?$filter=activityDisplayName eq 'Add member to role completed (PIM activation)' and activityDateTime ge 2025-03-01T00:00:00Z

Get Role Management Policies

GET /policies/roleManagementPolicies

Key Role Definition IDs

Role	ID
Global Administrator	62e90394-69f5-4237-9190-012177145e10
Security Administrator	194ae4cb-b126-40b2-bd5b-6091b380977d
User Administrator	fe930be7-5e62-47db-91af-98c3a49a38b1
Exchange Administrator	29232cdf-9323-42fd-ade2-1d097af3e4de
Privileged Role Administrator	e8611ab8-c189-46e8-94e1-60213ab1f814

Schedule Action Types

Action	Description
adminAssign	Admin assigns active or eligible role
adminRemove	Admin removes role assignment
adminUpdate	Admin updates existing assignment
adminExtend	Admin extends expiring assignment
adminRenew	Admin renews expired assignment
selfActivate	User activates eligible role
selfDeactivate	User deactivates active role
selfExtend	User requests extension
selfRenew	User requests renewal

Azure CLI Equivalent

# List PIM eligible assignments
az rest --method GET --url "https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilityScheduleInstances"

# List active assignments
az rest --method GET --url "https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleInstances"