In PIM, request for a role eligibility for a principal through the unifiedRoleEligibilityScheduleRequest object. This operation allows both admins and eligible users to add, revoke, or extend eligible assignments.
Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.
Permission type
Permissions (from least to most privileged)
Delegated (work or school account)
RoleEligibilitySchedule.ReadWrite.Directory
Delegated (personal Microsoft account)
Not supported
Application
RoleManagement.ReadWrite.Directory
HTTP request
POST /roleManagement/directory/roleEligibilityScheduleRequests
You can specify the following properties when creating an unifiedRoleEligibilityScheduleRequest.
Property
Type
Description
action
unifiedRoleScheduleRequestActions
Represents the type of operation on the role eligibility request.The possible values are: adminAssign, adminUpdate, adminRemove, selfActivate, selfDeactivate, adminExtend, adminRenew, selfExtend, selfRenew, unknownFutureValue.
adminAssign: For administrators to assign eligible roles to principals.
adminRemove: For administrators to remove eligible roles from principals.
adminUpdate: For administrators to change existing role eligibilities.
adminExtend: For administrators to extend expiring role eligibilities.
adminRenew: For administrators to renew expired eligibilities.
selfActivate: For users to activate their assignments.
selfDeactivate: For users to deactivate their active assignments.
selfExtend: For users to request to extend their expiring assignments.
SelfRenew: For users to request to renew their expired assignments.
appScopeId
String
Identifier of the app-specific scope when the role eligibility is scoped to an app. The scope of a role eligibility determines the set of resources for which the principal is eligible to access. App scopes are scopes that are defined and understood by this application only. Use / for tenant-wide app scopes. Use directoryScopeId to limit the scope to particular directory objects, for example, administrative units. Either directoryScopeId or appScopeId is required.
directoryScopeId
String
Identifier of the directory object representing the scope of the role eligibility. The scope of an role eligibility determines the set of resources for which the principal has been granted access. Directory scopes are shared scopes stored in the directory that are understood by multiple applications. Use / for tenant-wide scope. Use appScopeId to limit the scope to an application only. Either directoryScopeId or appScopeId is required.
isValidationOnly
Boolean
Determines whether the call is a validation or an actual call. Only set this property if you want to check whether an activation is subject to additional rules like MFA before actually submitting the request. Optional.
justification
String
A message provided by users and administrators when create they create the unifiedRoleEligibilityScheduleRequest object. Optional when action is adminRemove. Whether this property is required or optional is also dependent on the settings for the Azure AD role.
principalId
String
Identifier of the principal that has been granted the role eligibility. Required.
roleDefinitionId
String
Identifier of the unifiedRoleDefinition object that is being assigned to the principal. Required.
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new UnifiedRoleEligibilityScheduleRequest
{
Action = UnifiedRoleScheduleRequestActions.AdminAssign,
Justification = "Assign Attribute Assignment Admin eligibility to restricted user",
RoleDefinitionId = "8424c6f0-a189-499e-bbd0-26c1753c96d4",
DirectoryScopeId = "/",
PrincipalId = "071cc716-8147-4397-a5ba-b2105951cc0b",
ScheduleInfo = new RequestSchedule
{
StartDateTime = DateTimeOffset.Parse("2022-04-10T00:00:00Z"),
Expiration = new ExpirationPattern
{
Type = ExpirationPatternType.AfterDateTime,
EndDateTime = DateTimeOffset.Parse("2024-04-10T00:00:00Z"),
},
},
};
var result = await graphClient.RoleManagement.Directory.RoleEligibilityScheduleRequests.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new UnifiedRoleEligibilityScheduleRequest();
$requestBody->setAction(new UnifiedRoleScheduleRequestActions('adminassign'));
$requestBody->setJustification('Assign Attribute Assignment Admin eligibility to restricted user');
$requestBody->setRoleDefinitionId('8424c6f0-a189-499e-bbd0-26c1753c96d4');
$requestBody->setDirectoryScopeId('/');
$requestBody->setPrincipalId('071cc716-8147-4397-a5ba-b2105951cc0b');
$scheduleInfo = new RequestSchedule();
$scheduleInfo->setStartDateTime(new DateTime('2022-04-10T00:00:00Z'));
$scheduleInfoExpiration = new ExpirationPattern();
$scheduleInfoExpiration->setType(new ExpirationPatternType('afterdatetime'));
$scheduleInfoExpiration->setEndDateTime(new DateTime('2024-04-10T00:00:00Z'));
$scheduleInfo->setExpiration($scheduleInfoExpiration);
$requestBody->setScheduleInfo($scheduleInfo);
$result = $graphServiceClient->roleManagement()->directory()->roleEligibilityScheduleRequests()->post($requestBody);
Example 2: Admin to remove an existing role eligibility schedule request
In the following request, the admin creates a request to revoke the eligibility of a principal with ID 071cc716-8147-4397-a5ba-b2105951cc0b to a role with ID 8424c6f0-a189-499e-bbd0-26c1753c96d4.
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new UnifiedRoleEligibilityScheduleRequest
{
Action = "adminRemove",
RoleDefinitionId = "8424c6f0-a189-499e-bbd0-26c1753c96d4",
DirectoryScopeId = "/",
PrincipalId = "071cc716-8147-4397-a5ba-b2105951cc0b",
};
var result = await graphClient.RoleManagement.Directory.RoleEligibilityScheduleRequests.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new UnifiedRoleEligibilityScheduleRequest();
$requestBody->setAction('adminRemove');
$requestBody->setRoleDefinitionId('8424c6f0-a189-499e-bbd0-26c1753c96d4');
$requestBody->setDirectoryScopeId('/');
$requestBody->setPrincipalId('071cc716-8147-4397-a5ba-b2105951cc0b');
$result = $graphServiceClient->roleManagement()->directory()->roleEligibilityScheduleRequests()->post($requestBody);
The following is an example of the response. The response object shows a previous role eligibility for a principal is Revoked. The principal will no longer see their previously eligible role.
Note: The response object shown here might be shortened for readability.