Overview of identity protection APIs in Microsoft Graph
Namespace: microsoft.graph
Microsoft Entra ID 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.
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.
- APIs for manual remediation of risks by confirming a user as compromised or dismissing a risky user are also available.
signIn - Query Microsoft Graph for information about sign-ins with specific properties related to risk state, detail, and level. A sign-in risk represents the probability that an identity owner didn't authorize a given authentication request. 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.
- APIs for manual remediation of risks by confirming a service principal as compromised or dismissing a risky service principal are also available.
Automatic remediation of risks
Apart from manual remediation of risky users and service principals, you can also automatically remediate risks by integrating Identity Protection with Microsoft Entra Conditional Access policies. For more information, see Configure and enable risk policies.
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/v1.0/identityProtection/riskyUsers |
| GET risk detections | GET https://graph.microsoft.com/v1.0/identityProtection/riskDetections |
| GET a user's risk history | GET https://graph.microsoft.com/v1.0/identityProtection/riskyUsers/{riskyUserId}/history |
| CONFIRM a user as compromised | POST https://graph.microsoft.com/v1.0/identityProtection/riskyUsers/confirmCompromised |
| DISMISS a risky user | POST https://graph.microsoft.com/v1.0/identityProtection/riskyUsers/dismiss |
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 Microsoft Entra ID Protection license requirements.
How much data is available?
The availability of risk data is governed by the Microsoft Entra data retention policies.