Azure AD access reviews
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.
The access review API in this section is the recommended API for access reviews. The older version, access reviews API, will be deprecated.
You can use Azure AD access reviews to configure one-time or recurring access reviews for attestation of user's access rights.
Typical customer scenarios for access reviews of group memberships and application and Azure AD role access are:
Customers can review and certify guest user access to applications, Azure AD roles, and memberships of groups. 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 applications, Azure AD roles, and group memberships with access reviews.
Note that the access reviews feature, including the API, is included in Azure AD Premium P2. The tenant where an access review is being created must have a valid purchased or trial Azure AD Premium P2 or EMS E5 subscription.
The following table lists the methods that you can use to interact with access review-related resources.
|List accessReviewScheduleDefinitions||accessReviewScheduleDefinition collection||Get a list of the accessReviewScheduleDefinition objects and their properties.|
|Get accessReviewScheduleDefinition||accessReviewScheduleDefinition||Get an accessReviewScheduleDefinition object and its properties.|
|Create accessReviewScheduleDefinition||accessReviewScheduleDefinition||Create a new accessReviewScheduleDefinition.|
|Delete accessReviewScheduleDefinition||None.||Delete an accessReviewScheduleDefinition.|
|Update accessReviewScheduleDefinition||None.||Update properties of an accessReviewScheduleDefinition with a specified identifier.|
|accessReviewScheduleDefinition: filterByCurrentUser||accessReviewScheduleDefinition collection||Retrieves all definitions for which the calling user is a reviewer on one or more instance.|
|List accessReviewInstances||accessReviewInstance collection||Get a list of the accessReviewInstance objects and their properties.|
|Get accessReviewInstance||accessReviewInstance||Read the properties and relationships of an accessReviewInstance object.|
|Send accessReviewInstance reminder||None.||Send a reminder to the reviewers of an accessReviewInstance.|
|Stop accessReviewInstance||None.||Manually stop an accessReviewInstance.|
|Accept recommendations||None.||Allows the calling user to accept the decision recommendation for each NotReviewed accessReviewInstanceDecisionItem that they are the reviewer on for a specific accessReviewInstance.|
|Apply decisions||None.||Manually apply decisions on an accessReviewInstance.|
|Batch record decisions||None||Review batches of principals or resources in one call.|
|Reset decisions||None||Resets all decision items on an instance to
|accessReviewInstance: filterByCurrentUser||accessReviewInstance collection||Returns all instances on a given accessReviewScheduleDefinition for which the calling user is the reviewer of one or more decisions.|
|List accessReviewInstanceDecisionItems||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||None.||For any accessReviewInstanceDecisionItems that the calling user is assigned a reviewer on, calling user can record a decision by patching the decision object.|
|accessReviewInstanceDecisionItem: filterByCurrentUser||accessReviewInstanceDecisionItem collection||Retrieves all accessReviewInstanceDecisionItems objects where the calling use is the reviewer for a given accessReviewInstance.|
|List accessReviewHistoryDefinitions||accessReviewHistoryDefinition collection||Get a list of the accessReviewHistoryDefinition objects and their properties.|
|Create accessReviewHistoryDefinition||accessReviewHistoryDefinition||Create a new accessReviewHistoryDefinition object.|
|Get accessReviewHistoryDefinition||accessReviewHistoryDefinition||Read the properties and relationships of an accessReviewHistoryDefinition object.|
|generateDownloadUri||accessReviewHistoryDefinition||Generate a URI that can be used to retrieve review history data.|
|Get accessReviewPolicy||accessReviewPolicy||Read the properties and relationships of an accessReviewPolicy object.|
|Update accessReviewPolicy||accessReviewPolicy||Update the properties of an accessReviewPolicy object.|
|List definitions pending approval (deprecated)||accessReviewScheduleDefinition collection||Retrieves all definitions for which the calling user is a reviewer on one or more instance. This method is being deprecated and replaced by accessReviewScheduleDefinition: filterByCurrentUser.|
|List pendingAccessReviewInstances (deprecated)||accessReviewInstance collection.||Get all pending accessReviewInstance resources assigned to the calling user. This method is being deprecated and replaced by accessReviewInstance: filterByCurrentUser.|
|List accessReviewInstanceDecisionItems pending approval (deprecated)||accessReviewInstanceDecisionItem collection.||Get all accessReviewInstanceDecisionItems assigned to the calling user, for a specific accessReviewInstance. This method is being deprecated and replaced by accessReviewInstanceDecisionItem: filterByCurrentUse.|
Role and application permission authorization checks
The following directory 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.