One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.
For the directory (Azure AD) provider
Permission type
Permissions (from least to most privileged)
Delegated (work or school account)
RoleManagement.ReadWrite.Directory
Delegated (personal Microsoft account)
Not supported.
Application
RoleManagement.ReadWrite.Directory
For the entitlement management provider
Permission type
Permissions (from least to most privileged)
Delegated (work or school account)
EntitlementManagement.ReadWrite.All
Delegated (personal Microsoft account)
Not supported.
Application
EntitlementManagement.ReadWrite.All
HTTP request
Create a role assignment for the directory provider:
POST /roleManagement/directory/roleAssignments
Create a role assignment for the entitlement management provider:
POST /roleManagement/entitlementManagement/roleAssignments
Request headers
Name
Description
Authorization
Bearer {token}
Request body
In the request body, supply a JSON representation of unifiedRoleAssignment object. The request must have either a scope defined in Azure Active Directory (Azure AD) specified by directoryScopeId, or an application-specific scope specified by the appScopeId. Examples of Azure AD scopes are tenant (/), administrative unit, or application. For more information on appScope, see appScope.
The following table shows the properties that are required when you create a unifiedRoleAssignment object.
Parameter
Type
Description
roleDefinitionId
String
Identifier of the role definition the assignment is for.
principalId
String
The identifier of the principal to which the assignment is granted.
directoryScopeId
String
Identifier of the directory object representing the scope of the assignment. Either this property or appScopeId is required. 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.
appScopeId
String
Identifier of the app-specific scope when the assignment scope is app-specific. Either this property or directoryScopeId is required. 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.
Response
If successful, this method returns a 201 Created response code and a new unifiedRoleAssignment object in the response body.
Examples
Example 1: Create a role assignment with tenant scope
Request
The following is an example of the request. Note the use of the roleTemplateId for roleDefinitionId. roleDefinitionId can be either the service-wide template Id or the directory-specific roleDefinitionId.
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new UnifiedRoleAssignment();
$requestBody->set@odatatype('#microsoft.graph.unifiedRoleAssignment');
$requestBody->setRoleDefinitionId('c2cf284d-6c41-4e6b-afac-4b80928c9034');
$requestBody->setPrincipalId('f8ca5a85-489a-49a0-b555-0a6d81e56f0d');
$requestBody->setDirectoryScopeId('/');
$requestResult = $graphServiceClient->roleManagement()->directory()->roleAssignments()->post($requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new UnifiedRoleAssignment();
$requestBody->set@odatatype('#microsoft.graph.unifiedRoleAssignment');
$requestBody->setRoleDefinitionId('fe930be7-5e62-47db-91af-98c3a49a38b1');
$requestBody->setPrincipalId('f8ca5a85-489a-49a0-b555-0a6d81e56f0d');
$requestBody->setDirectoryScopeId('/administrativeUnits/5d107bba-d8e2-4e13-b6ae-884be90e5d1a');
$requestResult = $graphServiceClient->roleManagement()->directory()->roleAssignments()->post($requestBody);
Example 3 : Create a role assignment with application scope
Request
The following example assigns a principal the Application Administrator role at application scope. The object ID of the application registration is 661e1310-bd76-4795-89a7-8f3c8f855bfc.
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new UnifiedRoleAssignment();
$requestBody->set@odatatype('#microsoft.graph.unifiedRoleAssignment');
$requestBody->setPrincipalId('6b937a9d-c731-465b-a844-2d5b5368c161');
$requestBody->setRoleDefinitionId('9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3');
$requestBody->setDirectoryScopeId('/661e1310-bd76-4795-89a7-8f3c8f855bfc');
$requestResult = $graphServiceClient->roleManagement()->directory()->roleAssignments()->post($requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new UnifiedRoleAssignment();
$requestBody->setPrincipalId('679a9213-c497-48a4-830a-8d3d25d94ddc');
$requestBody->setRoleDefinitionId('ae79f266-94d4-4dab-b730-feca7e132178');
$requestBody->setAppScopeId('/AccessPackageCatalog/beedadfe-01d5-4025-910b-84abb9369997');
$requestResult = $graphServiceClient->roleManagement()->entitlementManagement()->roleAssignments()->post($requestBody);