Use Azure PIM to manage alerts with the REST API

Azure Privileged Identity Management (PIM) generates alerts when there's suspicious or unsafe activity in your organization in Azure Active Directory (Azure AD), part of Microsoft Entra. This article describes how to manage these alerts using the REST API.These alerts can also be managed through the Azure portal.

List alerts

To list alerts, you can use the Alerts - List For Scope REST API. To call the API, you must have access to the Microsoft.Authorization/roleAssignments/read operation at the specified scope. All built-in roles are granted access to this operation.

1. Start with the following request:

   GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleManagementAlerts?api-version=2022-08-01-preview
   

2. Within the URI, replace {subscriptionId} with the ID of the subscription for which you want to list the alerts.

Dismiss an alert

To dismiss an alert, you can use the Alerts - Update REST API. To call the API, you must have access to the Microsoft.Authorization/roleAssignments/write operation at the specified scope. Of the built-in roles, only Owner and User Access Administrator are granted access to this operation.

1. Start with the following request:

   PATCH https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleManagementAlerts/{roleManagementAlertName}?api-version=2022-08-01-preview
   

   {
     "Properties": {
       "IsActive": false
       }
   }
   

2. Within the URI, replace {subscriptionId} with the ID of the subscription for which you want to dismiss the alert.

3. Replace {roleManagementAlertName} with the name of the alert (for example, DuplicateRoleCreated).

Refresh an alert

To refresh a specific alert, you can use the Alerts - Refresh REST API. To call the API, you must have access to the Microsoft.Authorization/roleAssignments/write operation at the specified scope. Of the built-in roles, only Owner and User Access Administrator are granted access to this operation.

1. Start with the following request:

   POST https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleManagementAlerts/{roleManagementAlertName}/refresh?api-version=2022-08-01-preview
   

2. Within the URI, replace {subscriptionId} with the ID of the subscription for which you want to refresh the alerts.

3. Replace {roleManagementAlertName} with the name of the alert (for example, TooManyPermanentOwnersAssignedToResource).

4. Use the url provided in the Location header of the response to check the status of the alert refresh operation.

Refresh alerts

To refresh all alerts at a scope, you can use the Alerts - Refresh All REST API. To call the API, you must have access to the Microsoft.Authorization/roleAssignments/write operation at the specified scope. Of the built-in roles, only Owner and User Access Administrator are granted access to this operation.

1. Start with the following request:

   POST https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleManagementAlerts/refresh?api-version=2022-08-01-preview
   

2. Within the URI, replace {subscriptionId} with the ID of the subscription for which you want to refresh the alerts.

3. Use the url provided in the Location header of the response to check the status of the alert refresh operation.

Update an alert configuration

To update an alert configuration, you can use the Alert Configurations - Update REST API. To call the API, you must have access to the Microsoft.Authorization/roleAssignments/write operation at the specified scope. Of the built-in roles, only Owner and User Access Administrator are granted access to this operation.

1. Determine which configuration properties you want to update. Each alert configuration has different properties, which you can see by using the Role Management Alert Configurations - List For Scope REST API.

2. Start with the following request:

   PATCH https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleManagementAlertConfigurations/{roleManagementAlertConfigurationName}?api-version=2022-08-01-preview
   

   {
     "Properties": {
       "thresholdNumberOfOwners": 5,
       "thresholdPercentageOfOwnersOutOfAllRoleMembers": 10
       }
   }
   

3. Update the request body to include the properties you would like to update and the desired values.

4. Within the URI, replace {subscriptionId} with the ID of the subscription for which you want to refresh the alerts.

5. Replace {roleManagementAlertConfigurationName} with the name of the alert (for example, DuplicateRoleCreated).

Remediate an alert incident

To remediate an alert incident, you can use the Alert Incidents - Remediate REST API. To call the API, you must have access to the Microsoft.Authorization/roleAssignments/write operation at the specified scope. Of the built-in roles, only Owner and User Access Administrator are granted access to this operation.

1. Start with the following request:

   POST https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleManagementAlerts/{roleManagementAlertName}/alertIncidents/{roleManagementAlertIncidentName}/remediate?api-version=2022-08-01-preview
   

2. Within the URI, replace {subscriptionId} with the ID of the subscription for which you want to refresh the alerts.

3. Replace {roleManagementAlertName} with the name of the alert (for example, TooManyOwnersAssignedToResource).

4. Replace {roleManagementAlertIncidentName} with the name of the alert incident.