Working with the Microsoft Entra entitlement management API

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 entitlement management can help you manage access to groups, applications, and SharePoint Online sites for internal users as well as users outside your organization.

By creating access packages with the roles users need to have across those resources, and defining policies for who can request an access package and how long they can have an assignment to an access package, you can govern the lifecycle of access for both internal and external users.

The entitlement management resource types include:

• accessPackage: Defines the collections of resource roles and the policies for how one or more users may obtain access to those resources.
• accessPackageAssignmentPolicy: Specifies the policy by which subjects may request or be assigned an access package via an access package assignment.
• accessPackageAssignmentRequest: Created by a user who wishes to obtain an access package assignment.
• accessPackageAssignment: An assignment of an access package to a particular subject, for a period of time.
• accessPackageAssignmentResourceRole: Indicates the resource-specific role which a subject has been assigned through an access package assignment.
• accessPackageCatalog: A container for access packages.
• accessPackageResource: A reference to a resource associated with an access package catalog.
• accessPackageResourceRequest: A request to add a resource to an access package catalog.
• accessPackageResourceEnvironment: A reference to the geolocation of the resource. Applicable to Multi-Geo SharePoint Online sites.
• connectedOrganization: A connected organization for external users who can request access.
• entitlementManagementSettings: Tenant-wide settings for Microsoft Entra entitlement management.
• approval: represents the decisions associated with an access package request.

In addition, you can manage role assignments for users, groups of users, and service principals to entitlement management-specific roles through entitlement management role definitions.

For a tutorial that shows you how to use entitlement management to create a package of resources that internal users can self-service request, see Create an access package using Microsoft Graph APIs.

The tenant where entitlement management is being used must have sufficient purchased or trial licenses. For more information about license requirements for the entitlement management feature, see Entitlement management license requirements.

Methods

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

Method	Return type	Description
Get	entitlementManagementSettings	Read the properties of an entitlementManagementSettings object.
Update	entitlementManagementSettings	Update the properties of an entitlementManagementSettings object.
List accessPackages	accessPackage collection	Retrieve a list of accessPackage objects.
Create accessPackage	accessPackage	Create a new accessPackage object.
Get accessPackage	accessPackage	Read properties and relationships of an accessPackage object.
Update accessPackage	None	Update the properties of an accesspackage object.
Delete accessPackage		Delete accessPackage.
FilterByCurrentUser	accessPackage collection	Retrieve a list of accessPackage objects filtered on the signed-in user.
List accessPackageResourceRoleScopes	accessPackageResourceRoleScope collection	Retrieve a list of accessPackageResourceRoleScope objects for an access package.
Create accessPackageResourceRoleScope		Create a new accessPackageResourceRoleScope object for an access package.
List incompatibleAccessPackages	accessPackage collection	Retrieve a list of the incompatible accesspackage objects for this access package.
Add accessPackage to incompatibleAccessPackages	None	Add a link to indicate another accesspackage is incompatible with a specified access package.
Remove accessPackage from incompatibleAccessPackages	None	Remove a link that indicated an accesspackage was incompatible.
List incompatibleGroups	group collection	Retrieve a list of the incompatible group objects for this access package.
Add group to incompatibleGroups	None	Add a link to indicate membership of a group is incompatible with a specified access package.
Remove group from incompatibleGroups	None	Remove a link that indicated a group membership was incompatible.
List accessPackagesIncompatibleWith	accessPackage collection	Retrieve a list of the accesspackage objects which list this access package as incompatible.
moveToCatalog	None	Move an access package to a different catalog.
List accessPackageAssignmentPolicies	accessPackageAssignmentPolicy collection	Retrieve a list of accessPackageAssignmentPolicy objects.
Create accessPackageAssignmentPolicy	accessPackageAssignmentPolicy	Create a new accessPackageAssignmentPolicy object.
Get accessPackageAssignmentPolicy	accessPackageAssignmentPolicy	Read properties and relationships of an accessPackageAssignmentPolicy object.
Update accessPackageAssignmentPolicy	accessPackageAssignmentPolicy	Update the properties of an accessPackageAssignmentPolicy object.
Delete accessPackageAssignmentPolicy		Delete an accessPackageAssignmentPolicy.
List accessPackageAssignmentRequests	accessPackageAssignmentRequest collection	Retrieve a list of accessPackageAssignmentRequest objects.
Create accessPackageAssignmentRequest	accessPackageAssignmentRequest	Create a new accessPackageAssignmentRequest.
Get accessPackageAssignmentRequest	accessPackageAssignmentRequest	Read properties and relationships of an accessPackageAssignmentRequest object.
Delete accessPackageAssignmentRequest	None	Delete an accessPackageAssignmentRequest.
FilterByCurrentUser	accessPackageAssignmentRequest collection	Retrieve the list of accessPackageAssignmentRequest objects filtered on the signed-in user.
cancel	accessPackageAssignmentRequest collection	Cancel an accessPackageAssignmentRequest object that is in a cancellable state: accepted, pendingApproval, pendingNotBefore, pendingApprovalEscalated.
List accessPackageAssignments	accessPackageAssignment collection	Retrieve a list of accessPackageAssignment objects.
FilterByCurrentUser	accessPackageAssignment collection	Retrieve the list of accessPackageAssignment objects filtered on the signed-in user.
reprocess	None	Automatically reevaluate and enforce a user’s assignments for a specific access package.
additionalAccess accessPackageAssignment collection	Retrieve the list of accessPackageAssignment objects for users who have assignments to incompatible access packages.
List accessPackageAssignmentResourceRoles	accessPackageAssignmentResourceRole collection	Retrieve a list of accessPackageAssignmentResourceRole objects.
Get accessPackageAssignmentResourceRole	accessPackageAssignmentResourceRole	Retrieve a accessPackageAssignmentResourceRole object.
List accessPackageCatalogs	accessPackageCatalog collection	Retrieve a list of accessPackageCatalogs objects.
Create accessPackageCatalog	accessPackageCatalog	Create a new accessPackageCatalog object.
Get accessPackageCatalog	accessPackageCatalog	Read properties and relationships of an accessPackageCatalog object.
Update accessPackageCatalog	None	Update the properties of an accessPackageCatalog object.
Delete accessPackageCatalog		Delete an accessPackageCatalog.
List accessPackageCatalog resources	accessPackageResource collection	Retrieve a list of accessPackageResource objects.
List accessPackageCatalog resource roles	accessPackageResourceRole collection	Retrieve a list of accessPackageResourceRole objects.
List accessPackageResourceRequests	accessPackageResourceRequest collection	Read properties and relationships of accessPackageResourceRequest objects.
Create accessPackageResourceRequest	accessPackageCatalog	Create a new accessPackageResourceRequest object.
List accessPackageResourceEnvironments	accessPackageResourceEnvironment collection	Retrieve a list of accessPackageResourceEnvironment objects.
Get accessPackageResourceEnvironment	accessPackageResourceEnvironment	Read the properties and relationships of an accessPackageResourceEnvironment object.
List connectedOrganizations	connectedOrganization collection	Retrieve a list of connectedOrganization objects.
Create connectedOrganization	connectedOrganization	Create a new connectedOrganization object.
Get connectedOrganization	connectedOrganization	Read properties and relationships of a connectedOrganization object.
Update connectedOrganization	None	Update a connectedOrganization.
Delete connectedOrganization	None	Delete a connectedOrganization.
List internalSponsors	directoryObject collection	Retrieve a list of a connectedOrganization's internal sponsors.
List externalSponsors	directoryObject collection	Retrieve a list of a connectedOrganization's external sponsors.
Add internalSponsors	None	Add a user or group to a connectedOrganization's internal sponsors.
Add externalSponsors	None	Add a user or group to a connectedOrganization's external sponsors.
Remove internalSponsors	None	Remove a user or group from a connectedOrganization's internal sponsors.
Get approval	approval	Retrieve the properties of an approval object.
List approvalSteps	approvalStep collection	List the approvalStep objects associated with an approval object.
Get approvalStep	approvalStep	Retrieve the properties of an approvalStep object.
Update approvalStep	None	Apply approve or deny decision on an approvalStep object.

Types

• requestorSettings, approvalSettings, questions and assignmentReviewSettings - Used in an accessPackageAssignmentPolicy to specify who can request, who approves, and who reviews access package assignment requests on that policy.
• approvalStage - Used in the approvalSettings to specify the primary, backup, and escalation approvers.
• approvalStep - Used in approval to distinguish the different approval steps.
• userSet subtypes singleUser, groupMembers, connectedOrganizationMembers, requestorManager, internalSponsors, externalSponsors and targetUserSponsors - Used in requestorSettings, approvalStage, approvalStep and assignmentReviewSettings.
• accessPackageSubject - Used in the accessPackageAssignment as a subject user who has an access package assignment.
• identitySource - used in the connectedOrganization, one of azureActiveDirectoryTenant, crossCloudAzureActiveDirectoryTenant, domainIdentitySource or externalDomainFederation.

Related content

• What is Microsoft Entra entitlement management?