Assign custom admin roles using Graph API in Azure Active Directory

You can automate how you assign roles to user accounts Microsoft Graph API. This article covers POST, GET, and DELETE operations on roleAssignments.

Required permissions

Connect to your Azure AD tenant using a Global administrator account or Privileged Identity administrator to assign or remove roles.

POST Operations on RoleAssignment

HTTP request to create a role assignment between a user and a role definition.

POST

https://graph.windows.net/<tenantDomain-or-tenantId>/roleAssignments?api-version=1.61-internal

Body

{
    "principalId":"ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId":"194ae4cb-b126-40b2-bd5b-6091b380977d",
    "resourceScopes":["/"]
}

Response

HTTP/1.1 201 Created

HTTP request to create a role assignment where the principal or role definition does not exist

POST

https://graph.windows.net/<tenantDomain-or-tenantId>/roleAssignments?api-version=1.61-internal

Body

{
    "principalId":" 2142743c-a5b3-4983-8486-4532ccba12869",
    "roleDefinitionId":"194ae4cb-b126-40b2-bd5b-6091b380977d",
    "resourceScopes":["/"]
}

Response

HTTP/1.1 404 Not Found

HTTP request to create a single resource scoped role assignment on a built-in role definition.

Note

Built-in roles today have a limitation where they can be scoped only to the “/” organization-wide scope or the “/AU/*” scope. Single resource scoping does not work for built-in roles, but works for custom roles.

POST

https://graph.windows.net/<tenantDomain-or-tenantId>/roleAssignments?api-version=1.61-internal

Body

{
    "principalId":"ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId":"194ae4cb-b126-40b2-bd5b-6091b380977d",
    "resourceScopes":["/ab2e1023-bddc-4038-9ac1-ad4843e7e539"]
}

Response

HTTP/1.1 400 Bad Request
{
    "odata.error":
    {
        "code":"Request_BadRequest",
        "message":
        {
            "lang":"en",
            "value":"Provided authorization scope is not supported for built-in role definitions."},
            "values":
            [
                {
                    "item":"scope",
                    "value":"/ab2e1023-bddc-4038-9ac1-ad4843e7e539"
                }
            ]
        }
    }
}

GET Operations on RoleAssignment

HTTP request to get a role assignment for a given principal

GET

https://graph.windows.net/<tenantDomain-or-tenantId>/roleAssignments?api-version=1.61-internal&$filter=principalId eq ‘<object-id-of-principal>’

Response

HTTP/1.1 200 OK
{ 
    "id":"mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"
    "principalId":"ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId":"10dae51f-b6af-4016-8d66-8c2a99b929b3",
    "resourceScopes":["/"]
} ,
{
    "id":"CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
    "principalId":"ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId":"3671d40a-1aac-426c-a0c1-a3821ebd8218",
    "resourceScopes":["/"]
}

HTTP request to get a role assignment for a given role definition.

GET

https://graph.windows.net/<tenantDomain-or-tenantId>/roleAssignments?api-version=1.61-internal&$filter=roleDefinitionId eq ‘<object-id-or-template-id-of-role-definition>’

Response

HTTP/1.1 200 OK
{
    "id":"CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
    "principalId":"ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId":"3671d40a-1aac-426c-a0c1-a3821ebd8218",
    "resourceScopes":["/"]
}

HTTP request to get a role assignment by ID.

GET

https://graph.windows.net/<tenantDomain-or-tenantId>/roleAssignments/<id-of-role-assignment>?api-version=1.61-internal

Response

HTTP/1.1 200 OK
{ 
    "id":"mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"
    "principalId":"ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId":"10dae51f-b6af-4016-8d66-8c2a99b929b3",
    "resourceScopes":["/"]
}

DELETE Operations on RoleAssignment

HTTP request to delete a role assignment between a user and a role definition.

DELETE

https://graph.windows.net/<tenantDomain-or-tenantId>/roleAssignments/<id-of-role-assignment>?api-version=1.61-internal

Response

HTTP/1.1 204 No Content

HTTP request to delete a role assignment that no longer exists

DELETE

https://graph.windows.net/<tenantDomain-or-tenantId>/roleAssignments/<id-of-role-assignment>?api-version=1.61-internal

Response

HTTP/1.1 404 Not Found

HTTP request to delete a role assignment between self and built-in role definition

DELETE

https://graph.windows.net/<tenantDomain-or-tenantId>/roleAssignments/<id-of-role-assignment>?api-version=1.61-internal

Response

HTTP/1.1 400 Bad Request
{
    "odata.error":
    {
        "code":"Request_BadRequest",
        "message":
        {
            "lang":"en",
            "value":"Cannot remove self from built-in role definitions."},
            "values":null
        }
    }
}

Next steps