Use the Microsoft Graph identity protection 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.
Microsoft Entra Identity Protection is tool that allows organizations to discover, investigate, and remediate identity-based risks in their Microsoft Entra organization.
Use the following Microsoft Graph APIs to query user and service principal risks detected by Microsoft Entra ID Protection:
For users
riskDetection - Query Microsoft Graph for a list of both user and sign-in linked risk detections and associated information about the detection. Risk detections in Microsoft Entra ID Protection include any identified suspicious actions related to user accounts in the directory.
Caution
The identityRiskEvents API was deprecated and stopped returning data on January 10, 2020. It was replaced by the riskDetection API. For more information about the deprecation, see Deprecation of the identityRiskEvents API.
riskyUsers - Query Microsoft Graph for information about users that Microsoft Entra ID Protection detected as risky. User risk represents the probability that a given identity or account is compromised. These risks are calculated offline using Microsoft’s internal and external threat intelligence sources, including security researchers, law enforcement professionals, security teams at Microsoft, and other trusted sources.
signIn - Query Microsoft Graph for information about Microsoft Entra sign-ins with specific properties related to risk state, detail, and level. A sign-in risk represents the probability that a given authentication request isn’t authorized by the identity owner. These risks can be calculated in real-time or calculated offline using Microsoft’s internal and external threat intelligence sources, including security researchers, law enforcement professionals, security teams at Microsoft, and other trusted sources.
For service principals
servicePrincipalRiskDetection - Query Microsoft Graph for a list of service principal risk detections and associated information about the detections. Risk detections in Microsoft Entra ID Protection include any identified suspicious actions related to service principal accounts in the directory.
riskyServicePrincipals - Query Microsoft Graph for information about service principals that Microsoft Entra ID Protection detected as risky. Service principal risk represents the probability that a given identity or account is compromised. These risks are calculated asynchronously using data and patterns from Microsoft’s internal and external threat intelligence sources, including security researchers, law enforcement professionals, security teams at Microsoft, and other trusted sources.
What can I do with identity protection APIs in Microsoft Graph?
The following are popular requests:
| Operation | URL |
|---|---|
| GET risky users | GET https://graph.microsoft.com/beta/identityProtection/riskyUsers |
| GET risk detections | GET https://graph.microsoft.com/beta/identityProtection/riskDetections |
| GET a user's risk history | GET https://graph.microsoft.com/beta/identityProtection/riskyUsers/{riskyUserId}/history |
| CONFIRM a user as compromised | POST https://graph.microsoft.com/beta/identityProtection/riskyUsers/confirmCompromised |
| DISMISS a risky user | POST https://graph.microsoft.com/beta/identityProtection/riskyUsers/dismiss |
For specific guidance and additional information, see Identify and remediate risks using Microsoft Graph APIs.
What licenses do I need?
Microsoft Entra ID Protection for both users and service principals is a premium feature. You need specific licenses to access the full reports. For more information, see Identity Protection license requirements.
How much data is available?
The availability of risk data is governed by the Microsoft Entra data retention policies.