group: assignLicense

Namespace: microsoft.graph

Add or remove licenses on the group. Licenses assigned to the group will be assigned to all users in the group. To learn more about group-based licensing, see What is group-based licensing in Azure Active Directory.

To get the subscriptions available in the directory, perform a GET subscribedSkus request.

This API is supported in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

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) Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not supported.
Application Group.ReadWrite.All, Directory.ReadWrite.All

For delegated scenarios, the calling user needs one of the following Azure AD roles.

  • Directory Writers
  • Groups Administrator
  • License Administrator
  • User Administrator
  • Global Administrator

HTTP request

POST /groups/{id}/assignLicense

Request headers

Header Value
Authorization Bearer {token}. Required.
Content-Type application/json. Required.

Request body

In the request body, provide a JSON object with the following parameters.

Parameter Type Description
addLicenses assignedLicense collection A collection of assignedLicense objects that specify the licenses to add. You can disable servicePlans associated with a license by setting the disabledPlans property on an assignedLicense object.
removeLicenses Guid collection A collection of skuIds that identify the licenses to remove.

Response

If successful, this method returns a 202 Accepted response code and a target group object in the response body.

Examples

Example 1: Add licenses to the group

The following example adds licenses to the group.

Request

POST https://graph.microsoft.com/v1.0/groups/1132b215-826f-42a9-8cfe-1643d19d17fd/assignLicense
Content-type: application/json

{
  "addLicenses": [
    {
      "disabledPlans": [
        "113feb6c-3fe4-4440-bddc-54d774bf0318",
        "14ab5db5-e6c4-4b20-b4bc-13e36fd2227f"
      ],
      "skuId": "b05e124f-c7cc-45a0-a6aa-8cf78c946968"
    },
    {
      "disabledPlans": [
        "a413a9ff-720c-4822-98ef-2f37c2a21f4c"
      ],
      "skuId": "c7df2760-2c81-4ef7-b578-5b5392b571df"
    }
  ],
  "removeLicenses": []
}

Response

The response is the updated group object.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 202 Accepted
Content-type: application/json
location: https://graph.microsoft.com/v2/e8e96c2a-d787-4eb1-98d7-9e57c965f1de/directoryObjects/1132b215-826f-42a9-8cfe-1643d19d17fd/Microsoft.DirectoryServices.Group

{
  "id": "1132b215-826f-42a9-8cfe-1643d19d17fd",
  "createdDateTime": "2021-03-12T11:15:03Z",
  "groupTypes": [],
  "securityEnabled": true,
}

Example 2: Remove licenses from the group

The following example removes licenses from the group.

Request

POST https://graph.microsoft.com/v1.0/groups/1132b215-826f-42a9-8cfe-1643d19d17fd/assignLicense
Content-type: application/json

{
  "addLicenses": [],
  "removeLicenses": [
    "c7df2760-2c81-4ef7-b578-5b5392b571df",
    "b05e124f-c7cc-45a0-a6aa-8cf78c946968"
  ]
}

Response

The response is the updated group object.

Note: The response object shown here might be shortened for readability..

HTTP/1.1 202 Accepted
Content-type: application/json
location: https://graph.microsoft.com/v2/d056d009-17b3-4106-8173-cd3978ada898/directoryObjects/1ad75eeb-7e5a-4367-a493-9214d90d54d0/Microsoft.DirectoryServices.Group


{
  "id": "1ad75eeb-7e5a-4367-a493-9214d90d54d0",
  "deletedDateTime": null,
  "classification": null,
  "createdDateTime": "2018-04-18T22:05:03Z",
  "securityEnabled": true,

}