Cloud Licensing API
The Cloud Licensing API in Microsoft Graph (currently in preview) provides a modern, granular way to work with Microsoft 365 licensing data across subscriptions. It introduces a new conceptual model for how licenses are structured and enables more accurate accounting, reporting, and entitlement checks.
Key Terms
Let's start with some key terms:
- Allotments
- Usage rights
- Services
Allotments
Allotments are automatically generated pools of licenses created by Microsoft whenever a subscription is purchased or renewed. They break a subscription into smaller, manageable pieces.
Why allotments matter:
- Provide granular insight into how licenses from each subscription are used
- Reflect the actual backend state of licensing
- Help organizations track entitlements more accurately across multiple subscriptions
Usage Rights
A usage right means what specific Microsoft 365 services a user or group can use.
It is the core resource of the Cloud Licensing API.
What a usageRight includes:
- Whether a user or group is entitled to a service
- Whether the entitlement comes directly from a license or indirectly via group membership
- A more precise view than the legacy assignedLicenses property
Services
This represents a specific service (service plan) granted by an individual usageRight. It includes:
- planId – the service plan GUID
- planName – the human-readable plan name
- assignableTo – which types of objects the service can be assigned to (user, group, device, etc.)
This aligns with the service plan info used across Microsoft 365.
Permissions
New API also comes with a new set of permissions that are more granular:
CloudLicensing.Read.All: Allows the app to read all cloud licensing information.User-UsageRight.Read.All: Granular user permission which allow to access only usage rights and assignments of a user.
Calling the API
Examples are always better than words, so let's see how to call the API and what kind of data we get back.
List allotments
To list pools of licenses (allotments) in a tenant, you can use the endpoint:
GET https://graph.microsoft.com/beta/admin/cloudLicensing/allotments
The calling application must have either CloudLicensing.Read.All or higher privileged Directory.Read.All permissions.
The response will include details about each subscription, how many licenses are allotted, how many are consumed, and the specific services included in each allotment.
{
"value": [
{
"id": "rymmixukb637ax6mdkaxp3atbn6cu4kvu2aixwsl7visc337xjkz",
"assignableTo": "user,group",
"allottedUnits": 10000,
"consumedUnits": 1,
"skuId": "f30db892-07e9-47e9-837c-80727f46fd3d",
"skuPartNumber": "FLOW_FREE",
"services": [
{
"assignableTo": "none",
"planId": "113feb6c-3fe4-4440-bddc-54d774bf0318",
"planName": "EXCHANGE_S_FOUNDATION"
},
...
],
"subscriptions": []
},
{
"id": "rzg4ih4kj332cc4nl7cgn6ktbzwdw4ar62ajxg235bahcpzpvzcy",
"assignableTo": "user,group",
"allottedUnits": 25,
"consumedUnits": 21,
"skuId": "c42b9cae-ea4f-4ab7-9717-81576235ccac",
"skuPartNumber": "DEVELOPERPACK_E5",
"services": [
{
"assignableTo": "user,group",
"planId": "13b6da2c-0d84-450e-9f69-a33e221387ca",
"planName": "PEOPLE_SKILLS_FOUNDATION"
},
...
],
"subscriptions": []
},
{
"id": "rmemag6ljlz3iwwjj3ktp7kdby6h6mcaukkz5tso5qixa33p7yai",
"assignableTo": "user,group",
"allottedUnits": 10000,
"consumedUnits": 1,
"skuId": "5b631642-bd26-49fe-bd20-1daaa972ef80",
"skuPartNumber": "POWERAPPS_DEV",
"services": [
{
"assignableTo": "none",
"planId": "113feb6c-3fe4-4440-bddc-54d774bf0318",
"planName": "EXCHANGE_S_FOUNDATION"
},
...
],
"subscriptions": []
}
]
}
One interesting thing is that this endpoint supports OData $apply parameter for grouping and aggregation, which allows you to get more insights.
For example, aggregate total allotted and consumed units across all allotments:
GET https://graph.microsoft.com/beta/admin/cloudLicensing/allotments?$apply=aggregate(allottedUnits with sum as allottedUnits, consumedUnits with sum as consumedUnits)
And the response:
{
"value": [
{
"consumedUnits": 23,
"allottedUnits": 20025
}
]
}
From my testing, you need to specify the existing properties in the aggregate function, otherwise the response will not include custom properties (for example aggregate(allottedUnits with sum as totalAllottedUnits) ⇒ totalAllottedUnits will be missing in the response JSON). I guess is only temporary issue in the preview, but just keep in mind when you use the API.
Get allotment details
To get details about a specific allotment:
GET https://graph.microsoft.com/beta/admin/cloudLicensing/allotments/{allotmentId}
To find out who is consuming licenses from a specific allotment, you can expand the assignedTo relationship on the assignments endpoint:
GET https://graph.microsoft.com/beta/admin/cloudLicensing/allotments/{allotmentId}/assignments?$expand=assignedto($select=id)
The response will include the users and groups consuming licenses.
{
"value": [
{
"id": "ncn4yoqq3x7ameslv7ei3i7dbtocpzbwveisoixdqgile3q3bsfr",
"disabledServicePlanIds": [],
"assignedTo": {
"@odata.type": "#microsoft.graph.user",
"id": "893f9116-e024-4bc6-8e98-54c245129485"
}
}
]
}
List user's assignments
Let's check the opposite scenario, how to find out which allotments are assigned to a specific user:
GET https://graph.microsoft.com/beta/users/{user_id}/cloudLicensing/assignments?$expand=allotment($select=id,skuId,skuPartNumber)
The response will include the allotments that contribute licenses to the user, along with the SKU details.
{
"value": [
{
"id": "nay4zoaql57kjowjevbk7clda36alzv6beiqpigdvozbftv3esvt",
"disabledServicePlanIds": [],
"allotment": {
"id": "rymmixukb637ax6mdkaxp3atbn6cu4kvu2aixwsl7visc337xjkz",
"skuId": "f30db892-07e9-47e9-837c-80727f46fd3d",
"skuPartNumber": "FLOW_FREE"
}
},
...
]
}
List user's usage rights
In the previous query, I had to expand the allotment to get details about licenses. You can get the same information in a more direct way by listing usage rights for a user:
GET https://graph.microsoft.com/beta/me/cloudLicensing/usageRights
The response contains user's assigned licences including various services.
{
"value": [
{
"id": "iqzmy5bav66vq5ogdkav6rutbh6avwl5ayrawugdk5ysdtlxdblt",
"skuId": "f30db892-07e9-47e9-837c-80727f46fd3d",
"skuPartNumber": "FLOW_FREE",
"services": [
{
"assignableTo": "none",
"planId": "113feb6c-3fe4-4440-bddc-54d774bf0318",
"planName": "EXCHANGE_S_FOUNDATION"
},
{
"assignableTo": "user,group",
"planId": "17ab22cd-a0b3-4536-910a-cb6eb12696c0",
"planName": "DYN365_CDS_VIRAL"
},
{
"assignableTo": "user,group",
"planId": "50e68c76-46c6-4674-81f9-75456511b170",
"planName": "FLOW_P2_VIRAL"
}
]
},
...
]
}
Conclusion
The Cloud Licensing API is a powerful new tool for working with Microsoft 365 licensing data. It provides a more accurate and granular view of how licenses are allocated and consumed across subscriptions. By leveraging this API, organizations can gain better insights into their licensing usage, optimize their license management, and ensure compliance.
