Overview of access reviews 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.
Note
This is the recommended API for access reviews. The previous version of the access reviews API is deprecated.
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. |
| Get accessReviewScheduleDefinition | accessReviewScheduleDefinition | Get an accessReviewScheduleDefinition object and its properties. |
| Create definitions | accessReviewScheduleDefinition | Create a new accessReviewScheduleDefinition. |
| Delete accessReviewScheduleDefinition | None | Delete an accessReviewScheduleDefinition. |
| Update accessReviewScheduleDefinition | None | Update properties of an accessReviewScheduleDefinition with a specified identifier. |
| filterByCurrentUser | accessReviewScheduleDefinition collection | Retrieves all definitions for which the calling user is a reviewer on one or more instance. |
| 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. |
| sendReminder | None | Send a reminder to the reviewers of an accessReviewInstance. |
| stop | None | Manually stop 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. |
| applyDecisions | None | Manually apply decisions on an accessReviewInstance. |
| batchRecordDecisions | None | Review batches of principals or resources in one call. |
| resetDecisions | None | Resets all decision items on an instance to notReviewed. |
| filterByCurrentUser | accessReviewInstance collection | Returns all instances on a given accessReviewScheduleDefinition for which the calling user is the reviewer of one or more decisions. |
| 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 | None | For any accessReviewInstanceDecisionItems that the calling user is assigned a reviewer on, calling user can record a decision by patching the decision object. |
| filterByCurrentUser | accessReviewInstanceDecisionItem collection | Retrieves all accessReviewInstanceDecisionItems objects where the calling use is the reviewer for a given accessReviewInstance. |
| listPendingApproval (deprecated) | accessReviewInstanceDecisionItem collection | Get all accessReviewInstanceDecisionItems assigned to the calling user, for a specific accessReviewInstance. This method is being deprecated and replaced by accessReviewInstanceDecisionItem: filterByCurrentUser. |
| 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. |
| Policy | ||
| 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. |
Role and application permission authorization checks
The following Microsoft Entra roles are required for a calling user to manage access reviews.
| Operation | Application permissions | Least privileged directory role of the calling user |
|---|---|---|
| Read | AccessReview.Read.All or AccessReview.ReadWrite.All | Global Reader, Security Administrator, Security Reader, or User Administrator |
| Create, Update or Delete | AccessReview.ReadWrite.All | 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
- Walk through guided tutorials to learn how to use the access reviews API to review access to Microsoft Entra resources.