directory_role_assignment_schedule_requests

Creates, updates, deletes, gets or lists a directory_role_assignment_schedule_requests resource.

Overview

Name	`directory_role_assignment_schedule_requests`
Type	Resource
Id	`entra_id.role_management.directory_role_assignment_schedule_requests`

Fields

The following fields are returned by SELECT queries:

get
list

Retrieved navigation property

Name	Datatype	Description
`id`	`string`	The unique identifier for an entity. Read-only.
`action`		Represents the type of the operation on the role assignment request. The possible values are: adminAssign, adminUpdate, adminRemove, selfActivate, selfDeactivate, adminExtend, adminRenew, selfExtend, selfRenew, unknownFutureValue. adminAssign: For administrators to assign roles to principals.adminRemove: For administrators to remove principals from roles. adminUpdate: For administrators to change existing role assignments.adminExtend: For administrators to extend expiring assignments.adminRenew: For administrators to renew expired assignments.selfActivate: For principals to activate their assignments.selfDeactivate: For principals to deactivate their active assignments.selfExtend: For principals to request to extend their expiring assignments.selfRenew: For principals to request to renew their expired assignments.
`activatedUsing`		If the request is from an eligible administrator to activate a role, this parameter will show the related eligible assignment for that activation. Otherwise, it's null. Supports $expand and $select nested in $expand.
`appScope`		Read-only property with details of the app-specific scope when the assignment is scoped to an app. Nullable. Supports $expand.
`appScopeId`	`string`	Identifier of the app-specific scope when the assignment is scoped to an app. The scope of an assignment determines the set of resources for which the principal has been granted 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. Supports $filter (eq, ne, and on null values).
`approvalId`	`string`	The identifier of the approval of the request.
`completedDateTime`	`string (date-time)`	The request completion date time. (pattern: `^[0-9]{4,}-(0[1-9]\|1[012])-(0[1-9]\|[12][0-9]\|3[01])T([01][0-9]\|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z\|[+-][0-9][0-9]:[0-9][0-9])$`)
`createdBy`		The principal that created the request.
`createdDateTime`	`string (date-time)`	The request creation date time. (pattern: `^[0-9]{4,}-(0[1-9]\|1[012])-(0[1-9]\|[12][0-9]\|3[01])T([01][0-9]\|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z\|[+-][0-9][0-9]:[0-9][0-9])$`)
`customData`	`string`	Free text field to define any custom data for the request. Not used.
`directoryScope`		The directory object that is the scope of the assignment. Read-only. Supports $expand.
`directoryScopeId`	`string`	Identifier of the directory object representing the scope of the assignment. The scope of an assignment 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. Supports $filter (eq, ne, and on null values).
`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.
`justification`	`string`	A message provided by users and administrators when create they create the unifiedRoleAssignmentScheduleRequest object.
`principal`		The principal that's getting a role assignment through the request. Supports $expand and $select nested in $expand for id only.
`principalId`	`string`	Identifier of the principal that has been granted the assignment. Can be a user, role-assignable group, or a service principal. Supports $filter (eq, ne).
`roleDefinition`		Detailed information for the unifiedRoleDefinition object that is referenced through the roleDefinitionId property. Supports $expand and $select nested in $expand.
`roleDefinitionId`	`string`	Identifier of the unifiedRoleDefinition object that is being assigned to the principal. Supports $filter (eq, ne).
`scheduleInfo`		The period of the role assignment. Recurring schedules are currently unsupported.
`status`	`string`	The status of the request. Not nullable. The possible values are: Canceled, Denied, Failed, Granted, PendingAdminDecision, PendingApproval, PendingProvisioning, PendingScheduleCreation, Provisioned, Revoked, and ScheduleCreated. Not nullable.
`targetSchedule`		The schedule for an eligible role assignment that is referenced through the targetScheduleId property. Supports $expand and $select nested in $expand.
`targetScheduleId`	`string`	Identifier of the schedule object that's linked to the assignment request. Supports $filter (eq, ne).
`ticketInfo`		Ticket details linked to the role assignment request including details of the ticket number and ticket system.

Retrieved collection

Name	Datatype	Description
`id`	`string`	The unique identifier for an entity. Read-only.
`action`		Represents the type of the operation on the role assignment request. The possible values are: adminAssign, adminUpdate, adminRemove, selfActivate, selfDeactivate, adminExtend, adminRenew, selfExtend, selfRenew, unknownFutureValue. adminAssign: For administrators to assign roles to principals.adminRemove: For administrators to remove principals from roles. adminUpdate: For administrators to change existing role assignments.adminExtend: For administrators to extend expiring assignments.adminRenew: For administrators to renew expired assignments.selfActivate: For principals to activate their assignments.selfDeactivate: For principals to deactivate their active assignments.selfExtend: For principals to request to extend their expiring assignments.selfRenew: For principals to request to renew their expired assignments.
`activatedUsing`		If the request is from an eligible administrator to activate a role, this parameter will show the related eligible assignment for that activation. Otherwise, it's null. Supports $expand and $select nested in $expand.
`appScope`		Read-only property with details of the app-specific scope when the assignment is scoped to an app. Nullable. Supports $expand.
`appScopeId`	`string`	Identifier of the app-specific scope when the assignment is scoped to an app. The scope of an assignment determines the set of resources for which the principal has been granted 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. Supports $filter (eq, ne, and on null values).
`approvalId`	`string`	The identifier of the approval of the request.
`completedDateTime`	`string (date-time)`	The request completion date time. (pattern: `^[0-9]{4,}-(0[1-9]\|1[012])-(0[1-9]\|[12][0-9]\|3[01])T([01][0-9]\|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z\|[+-][0-9][0-9]:[0-9][0-9])$`)
`createdBy`		The principal that created the request.
`createdDateTime`	`string (date-time)`	The request creation date time. (pattern: `^[0-9]{4,}-(0[1-9]\|1[012])-(0[1-9]\|[12][0-9]\|3[01])T([01][0-9]\|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z\|[+-][0-9][0-9]:[0-9][0-9])$`)
`customData`	`string`	Free text field to define any custom data for the request. Not used.
`directoryScope`		The directory object that is the scope of the assignment. Read-only. Supports $expand.
`directoryScopeId`	`string`	Identifier of the directory object representing the scope of the assignment. The scope of an assignment 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. Supports $filter (eq, ne, and on null values).
`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.
`justification`	`string`	A message provided by users and administrators when create they create the unifiedRoleAssignmentScheduleRequest object.
`principal`		The principal that's getting a role assignment through the request. Supports $expand and $select nested in $expand for id only.
`principalId`	`string`	Identifier of the principal that has been granted the assignment. Can be a user, role-assignable group, or a service principal. Supports $filter (eq, ne).
`roleDefinition`		Detailed information for the unifiedRoleDefinition object that is referenced through the roleDefinitionId property. Supports $expand and $select nested in $expand.
`roleDefinitionId`	`string`	Identifier of the unifiedRoleDefinition object that is being assigned to the principal. Supports $filter (eq, ne).
`scheduleInfo`		The period of the role assignment. Recurring schedules are currently unsupported.
`status`	`string`	The status of the request. Not nullable. The possible values are: Canceled, Denied, Failed, Granted, PendingAdminDecision, PendingApproval, PendingProvisioning, PendingScheduleCreation, Provisioned, Revoked, and ScheduleCreated. Not nullable.
`targetSchedule`		The schedule for an eligible role assignment that is referenced through the targetScheduleId property. Supports $expand and $select nested in $expand.
`targetScheduleId`	`string`	Identifier of the schedule object that's linked to the assignment request. Supports $filter (eq, ne).
`ticketInfo`		Ticket details linked to the role assignment request including details of the ticket number and ticket system.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`unified_role_assignment_schedule_request_id`		In PIM, read the details of a request for an active and persistent role assignment made through the unifiedRoleAssignmentScheduleRequest object.
`list`	`select`			Retrieve the requests for active role assignments to principals. The active assignments include those made through assignments and activation requests, and directly through the role assignments API. The role assignments can be permanently active with or without an expiry date, or temporarily active after user activation of eligible assignments.
`insert`	`insert`			In PIM, carry out the following operations through the unifiedRoleAssignmentScheduleRequest object: To call this API to update, renew, and extend assignments for yourself, you must have multifactor authentication (MFA) enforced, and running the query in a session in which they were challenged for MFA. See Enable per-user Microsoft Entra multifactor authentication to secure sign-in events.
`update`	`update`	`unified_role_assignment_schedule_request_id`
`delete`	`delete`	`unified_role_assignment_schedule_request_id`	`If-Match`
`cancel`	`exec`	`unified_role_assignment_schedule_request_id`		Immediately cancel a unifiedRoleAssignmentScheduleRequest object that is in a Granted status, and have the system automatically delete the canceled request after 30 days. After calling this action, the status of the canceled unifiedRoleAssignmentScheduleRequest changes to Canceled.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`unified_role_assignment_schedule_request_id`	`string`	The unique identifier of unifiedRoleAssignmentScheduleRequest
`If-Match`	`string`	ETag

`SELECT` examples

get
list

In PIM, read the details of a request for an active and persistent role assignment made through the unifiedRoleAssignmentScheduleRequest object.

SELECT
id,
action,
activatedUsing,
appScope,
appScopeId,
approvalId,
completedDateTime,
createdBy,
createdDateTime,
customData,
directoryScope,
directoryScopeId,
isValidationOnly,
justification,
principal,
principalId,
roleDefinition,
roleDefinitionId,
scheduleInfo,
status,
targetSchedule,
targetScheduleId,
ticketInfo
FROM entra_id.role_management.directory_role_assignment_schedule_requests
WHERE unified_role_assignment_schedule_request_id = '{{ unified_role_assignment_schedule_request_id }}' -- required
;

Retrieve the requests for active role assignments to principals. The active assignments include those made through assignments and activation requests, and directly through the role assignments API. The role assignments can be permanently active with or without an expiry date, or temporarily active after user activation of eligible assignments.

SELECT
id,
action,
activatedUsing,
appScope,
appScopeId,
approvalId,
completedDateTime,
createdBy,
createdDateTime,
customData,
directoryScope,
directoryScopeId,
isValidationOnly,
justification,
principal,
principalId,
roleDefinition,
roleDefinitionId,
scheduleInfo,
status,
targetSchedule,
targetScheduleId,
ticketInfo
FROM entra_id.role_management.directory_role_assignment_schedule_requests
;

`INSERT` examples

insert
Manifest

In PIM, carry out the following operations through the unifiedRoleAssignmentScheduleRequest object: To call this API to update, renew, and extend assignments for yourself, you must have multifactor authentication (MFA) enforced, and running the query in a session in which they were challenged for MFA. See Enable per-user Microsoft Entra multifactor authentication to secure sign-in events.

INSERT INTO entra_id.role_management.directory_role_assignment_schedule_requests (
id,
approvalId,
completedDateTime,
createdBy,
createdDateTime,
customData,
status,
action,
appScopeId,
directoryScopeId,
isValidationOnly,
justification,
principalId,
roleDefinitionId,
scheduleInfo,
targetScheduleId,
ticketInfo,
activatedUsing,
appScope,
directoryScope,
principal,
roleDefinition,
targetSchedule
)
SELECT 
'{{ id }}',
'{{ approvalId }}',
'{{ completedDateTime }}',
'{{ createdBy }}',
'{{ createdDateTime }}',
'{{ customData }}',
'{{ status }}',
'{{ action }}',
'{{ appScopeId }}',
'{{ directoryScopeId }}',
{{ isValidationOnly }},
'{{ justification }}',
'{{ principalId }}',
'{{ roleDefinitionId }}',
'{{ scheduleInfo }}',
'{{ targetScheduleId }}',
'{{ ticketInfo }}',
'{{ activatedUsing }}',
'{{ appScope }}',
'{{ directoryScope }}',
'{{ principal }}',
'{{ roleDefinition }}',
'{{ targetSchedule }}'
RETURNING
id,
action,
activatedUsing,
appScope,
appScopeId,
approvalId,
completedDateTime,
createdBy,
createdDateTime,
customData,
directoryScope,
directoryScopeId,
isValidationOnly,
justification,
principal,
principalId,
roleDefinition,
roleDefinitionId,
scheduleInfo,
status,
targetSchedule,
targetScheduleId,
ticketInfo
;

# Description fields are for documentation purposes
- name: directory_role_assignment_schedule_requests
props:
  - name: id
    value: "{{ id }}"
    description: |
      The unique identifier for an entity. Read-only.
  - name: approvalId
    value: "{{ approvalId }}"
    description: |
      The identifier of the approval of the request.
  - name: completedDateTime
    value: "{{ completedDateTime }}"
    description: |
      The request completion date time.
  - name: createdBy
    value: "{{ createdBy }}"
    description: |
      The principal that created the request.
  - name: createdDateTime
    value: "{{ createdDateTime }}"
    description: |
      The request creation date time.
  - name: customData
    value: "{{ customData }}"
    description: |
      Free text field to define any custom data for the request. Not used.
  - name: status
    value: "{{ status }}"
    description: |
      The status of the request. Not nullable. The possible values are: Canceled, Denied, Failed, Granted, PendingAdminDecision, PendingApproval, PendingProvisioning, PendingScheduleCreation, Provisioned, Revoked, and ScheduleCreated. Not nullable.
  - name: action
    value: "{{ action }}"
    description: |
      Represents the type of the operation on the role assignment request. The possible values are: adminAssign, adminUpdate, adminRemove, selfActivate, selfDeactivate, adminExtend, adminRenew, selfExtend, selfRenew, unknownFutureValue. adminAssign: For administrators to assign roles to principals.adminRemove: For administrators to remove principals from roles. adminUpdate: For administrators to change existing role assignments.adminExtend: For administrators to extend expiring assignments.adminRenew: For administrators to renew expired assignments.selfActivate: For principals to activate their assignments.selfDeactivate: For principals to deactivate their active assignments.selfExtend: For principals to request to extend their expiring assignments.selfRenew: For principals to request to renew their expired assignments.
  - name: appScopeId
    value: "{{ appScopeId }}"
    description: |
      Identifier of the app-specific scope when the assignment is scoped to an app. The scope of an assignment determines the set of resources for which the principal has been granted 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. Supports $filter (eq, ne, and on null values).
  - name: directoryScopeId
    value: "{{ directoryScopeId }}"
    description: |
      Identifier of the directory object representing the scope of the assignment. The scope of an assignment 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. Supports $filter (eq, ne, and on null values).
  - name: isValidationOnly
    value: {{ isValidationOnly }}
    description: |
      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.
  - name: justification
    value: "{{ justification }}"
    description: |
      A message provided by users and administrators when create they create the unifiedRoleAssignmentScheduleRequest object.
  - name: principalId
    value: "{{ principalId }}"
    description: |
      Identifier of the principal that has been granted the assignment. Can be a user, role-assignable group, or a service principal. Supports $filter (eq, ne).
  - name: roleDefinitionId
    value: "{{ roleDefinitionId }}"
    description: |
      Identifier of the unifiedRoleDefinition object that is being assigned to the principal. Supports $filter (eq, ne).
  - name: scheduleInfo
    value: "{{ scheduleInfo }}"
    description: |
      The period of the role assignment. Recurring schedules are currently unsupported.
  - name: targetScheduleId
    value: "{{ targetScheduleId }}"
    description: |
      Identifier of the schedule object that's linked to the assignment request. Supports $filter (eq, ne).
  - name: ticketInfo
    value: "{{ ticketInfo }}"
    description: |
      Ticket details linked to the role assignment request including details of the ticket number and ticket system.
  - name: activatedUsing
    value: "{{ activatedUsing }}"
    description: |
      If the request is from an eligible administrator to activate a role, this parameter will show the related eligible assignment for that activation. Otherwise, it's null. Supports $expand and $select nested in $expand.
  - name: appScope
    value: "{{ appScope }}"
    description: |
      Read-only property with details of the app-specific scope when the assignment is scoped to an app. Nullable. Supports $expand.
  - name: directoryScope
    value: "{{ directoryScope }}"
    description: |
      The directory object that is the scope of the assignment. Read-only. Supports $expand.
  - name: principal
    value: "{{ principal }}"
    description: |
      The principal that's getting a role assignment through the request. Supports $expand and $select nested in $expand for id only.
  - name: roleDefinition
    value: "{{ roleDefinition }}"
    description: |
      Detailed information for the unifiedRoleDefinition object that is referenced through the roleDefinitionId property. Supports $expand and $select nested in $expand.
  - name: targetSchedule
    value: "{{ targetSchedule }}"
    description: |
      The schedule for an eligible role assignment that is referenced through the targetScheduleId property. Supports $expand and $select nested in $expand.

`UPDATE` examples

update

No description available.

UPDATE entra_id.role_management.directory_role_assignment_schedule_requests
SET 
id = '{{ id }}',
approvalId = '{{ approvalId }}',
completedDateTime = '{{ completedDateTime }}',
createdBy = '{{ createdBy }}',
createdDateTime = '{{ createdDateTime }}',
customData = '{{ customData }}',
status = '{{ status }}',
action = '{{ action }}',
appScopeId = '{{ appScopeId }}',
directoryScopeId = '{{ directoryScopeId }}',
isValidationOnly = {{ isValidationOnly }},
justification = '{{ justification }}',
principalId = '{{ principalId }}',
roleDefinitionId = '{{ roleDefinitionId }}',
scheduleInfo = '{{ scheduleInfo }}',
targetScheduleId = '{{ targetScheduleId }}',
ticketInfo = '{{ ticketInfo }}',
activatedUsing = '{{ activatedUsing }}',
appScope = '{{ appScope }}',
directoryScope = '{{ directoryScope }}',
principal = '{{ principal }}',
roleDefinition = '{{ roleDefinition }}',
targetSchedule = '{{ targetSchedule }}'
WHERE 
unified_role_assignment_schedule_request_id = '{{ unified_role_assignment_schedule_request_id }}' --required
RETURNING
id,
action,
activatedUsing,
appScope,
appScopeId,
approvalId,
completedDateTime,
createdBy,
createdDateTime,
customData,
directoryScope,
directoryScopeId,
isValidationOnly,
justification,
principal,
principalId,
roleDefinition,
roleDefinitionId,
scheduleInfo,
status,
targetSchedule,
targetScheduleId,
ticketInfo;

`DELETE` examples

delete

No description available.

DELETE FROM entra_id.role_management.directory_role_assignment_schedule_requests
WHERE unified_role_assignment_schedule_request_id = '{{ unified_role_assignment_schedule_request_id }}' --required
AND If-Match = '{{ If-Match }}'
;

Lifecycle Methods

cancel

Immediately cancel a unifiedRoleAssignmentScheduleRequest object that is in a Granted status, and have the system automatically delete the canceled request after 30 days. After calling this action, the status of the canceled unifiedRoleAssignmentScheduleRequest changes to Canceled.

EXEC entra_id.role_management.directory_role_assignment_schedule_requests.cancel 
@unified_role_assignment_schedule_request_id='{{ unified_role_assignment_schedule_request_id }}' --required
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​