Edit

Overview of access reviews APIs

  • Article

Namespace: microsoft.graph

Use Microsoft Entra access reviews to configure one-time or recurring access reviews for attestation of a principal's right to access Microsoft Entra resources. The principals are users or applications (service principals). The Microsoft Entra resources include groups, applications (service principals), access packages, and privileged roles. Access reviews is a feature of Microsoft Entra ID Governance.

Typical customer scenarios for access reviews include:

  • Customers can review and certify guest user access to groups through group memberships. Reviewers can use the insights that are provided to efficiently decide whether guests should have continued access.
  • Customers can review and certify employee access to Microsoft Entra resources.
  • Customers can review and audit assignments to Microsoft Entra ID privileged roles. This supports organizations in the management of privileged access.

The tenant where an access review is being created or managed via the API must have sufficient purchased or trial licenses. For more information about the license requirements, see Access reviews license requirements.

Note

This article describes how to export personal data from a device or service. These steps can be used to support your obligations under the General Data Protection Regulation (GDPR). Authorized tenant admins can use Microsoft Graph to correct, update, or delete identifiable information about end users, including customer and employee user profiles or personal data, such as a user's name, work title, address, or phone number, in your Microsoft Entra ID environment.

Methods

The following table lists the methods that you can use to interact with access review-related resources.

Method Return type Description
Schedule definitions
List definitions accessReviewScheduleDefinition collection Get a list of the accessReviewScheduleDefinition objects and their properties.
Create definitions accessReviewScheduleDefinition Create a new accessReviewScheduleDefinition object.
Get accessReviewScheduleDefinition accessReviewScheduleDefinition Read the properties and relationships of an accessReviewScheduleDefinition object.
Update accessReviewScheduleDefinition accessReviewScheduleDefinition Update the properties of an accessReviewScheduleDefinition object.
Delete accessReviewScheduleDefinition None Deletes an accessReviewScheduleDefinition object.
filterByCurrentUser accessReviewScheduleDefinition collection Returns all definitions where the calling user is the reviewer of any instances.
Instances
List instances accessReviewInstance collection Get a list of the accessReviewInstance objects and their properties.
Get accessReviewInstance accessReviewInstance Read the properties and relationships of an accessReviewInstance object.
stop None Manually stop an accessReviewInstance.
sendReminder None Send a reminder to the reviewers of an accessReviewInstance.
resetDecisions None Resets all decision items on an instance to notReviewed
applyDecisions None Manually apply decision on an accessReviewInstance.
acceptRecommendations None Allows the calling user to accept the decision recommendation for each NotReviewed accessReviewInstanceDecisionItem that they are the reviewer on for a specific accessReviewInstance.
batchRecordDecisions None Review batches of principals or resources in one call.
filterByCurrentUser accessReviewInstance collection Returns all instance objects on a definition for which the calling user is the reviewer.
Instance decision items
List decisions accessReviewInstanceDecisionItem collection Get a list of the accessReviewInstanceDecisionItem objects and their properties.
Get accessReviewInstanceDecisionItem accessReviewInstanceDecisionItem Read the properties and relationships of an accessReviewInstanceDecisionItem object.
Update accessReviewInstanceDecisionItem accessReviewInstanceDecisionItem Update the properties of an accessReviewInstanceDecisionItem object.
accessReviewInstanceDecisionItem: filterByCurrentUser accessReviewInstanceDecisionItem collection Returns the decision items for which the calling user is the reviewer of.
History definitions
List historyDefinitions accessReviewHistoryDefinition collection Get a list of the accessReviewHistoryDefinition objects and their properties.
Create historyDefinitions accessReviewHistoryDefinition Create a new accessReviewHistoryDefinition object.
Get accessReviewHistoryDefinition accessReviewHistoryDefinition Read the properties and relationships of an accessReviewHistoryDefinition object.
generateDownloadUri accessReviewHistoryInstance Generate a URI for an instance that can be used to retrieve review history data.
List instances accessReviewHistoryInstance Retrieve a list of the accessReviewHistoryInstance objects and their properties.

Role and application permission authorization checks

The following Microsoft Entra roles are required for a calling user to manage access reviews.

Operation Application permissions Required directory role of the calling user
Read AccessReview.Read.All or AccessReview.ReadWrite.All Global Administrator, Global Reader, Security Administrator, Security Reader or User Administrator
Create, Update or Delete AccessReview.ReadWrite.All Global Administrator or User Administrator

In addition, a user who is an assigned reviewer of an access review can manage their decisions, without needing to be in a directory role.

Related content