License Optimizer

M365 License Optimizer

This skill provides comprehensive knowledge for identifying license waste, recommending right-sizing, managing group-based licensing, and generating savings reports for MSP/CSP customer review meetings via Graph API.

Integration Context Contract

• Canonical contract: docs/integration-context.md

* Use sovereign cloud values from the canonical contract when applicable.

Fail fast before Graph calls when required context is missing or invalid. Redact tenant/user identifiers in outputs.

Base URL

https://graph.microsoft.com/v1.0

All endpoints below are relative to this base URL.

API Endpoints

License Inventory

List Tenant SKUs

GET /subscribedSkus

Response fields:

• skuPartNumber — friendly SKU identifier
• skuId — GUID for API operations
• prepaidUnits.enabled — total purchased licenses
• consumedUnits — currently assigned licenses
• appliesTo — User or Company
• servicePlans[] — individual service plans included in the SKU

Available licenses formula: prepaidUnits.enabled - consumedUnits

List User License Details

GET /users?$select=displayName,userPrincipalName,assignedLicenses,signInActivity,accountEnabled
  &$filter=assignedLicenses/$count ne 0
  &$count=true
  &$orderby=signInActivity/lastSignInDateTime asc
Header: ConsistencyLevel: eventual

Assign License Request Body

POST /users/{userId}/assignLicense
{
  "addLicenses": [
    {
      "skuId": "05e9a617-0261-4cee-bb44-138d3ef5d965",
      "disabledPlans": [
        "efb87545-963c-4e0d-99df-69c6916d9eb0"
      ]
    }
  ],
  "removeLicenses": []
}

Remove License Request Body

POST /users/{userId}/assignLicense
{
  "addLicenses": [],
  "removeLicenses": ["05e9a617-0261-4cee-bb44-138d3ef5d965"]
}

Group-Based Licensing

Assign licenses to a group so all members automatically inherit the license:

Assign License to Group

POST /groups/{groupId}/assignLicense
{
  "addLicenses": [
    {
      "skuId": "05e9a617-0261-4cee-bb44-138d3ef5d965",
      "disabledPlans": []
    }
  ],
  "removeLicenses": []
}

Check Group License Processing Status

GET /groups/{groupId}?$select=assignedLicenses,licenseProcessingState

licenseProcessingState values: QueuedForProcessing, ProcessingInProgress, ProcessingComplete.

Find Users with Group-Based License Errors

GET /groups/{groupId}/membersWithLicenseErrors

Returns users whose license could not be applied due to conflicts or insufficient licenses.

Common SKU Reference

Prices are approximate list prices. CSP/EA pricing varies.

Service Plan ID Reference (Top 20)

Optimization Patterns

Pattern 1: Inactive License Detection

Users with a license but no sign-in for 30+ days:

GET /users?$filter=signInActivity/lastSignInDateTime le {30daysAgo}
  &$select=displayName,userPrincipalName,assignedLicenses,signInActivity,accountEnabled
  &$count=true
  &$orderby=signInActivity/lastSignInDateTime asc
Header: ConsistencyLevel: eventual

Quick wins:

• Disabled accounts with licenses → remove licenses immediately
• Accounts with no sign-in ever → likely service accounts or stale provisioning
• Accounts with 60+ days inactive → candidate for license removal or downgrade

Pattern 2: Downgrade Analysis

Pattern 3: Service Plan Usage Verification

Before downgrading, verify which service plans the user actually uses:

GET /users/{userId}/licenseDetails

Cross-reference servicePlans with actual usage:

• Exchange Online: GET /reports/getMailboxUsageDetail(period='D30') — check mailbox activity
• SharePoint: GET /reports/getSharePointActivityUserDetail(period='D30') — check file activity
• Teams: GET /reports/getTeamsUserActivityUserDetail(period='D30') — check Teams activity
• Office Apps: GET /reports/getOffice365ActivationsUserDetail — check activation status

Pattern 4: Group-Based License Cleanup

1. GET /groups?$filter=assignedLicenses/$count ne 0&$count=true — find groups with licenses
2. For each group: GET /groups/{id}/members?$count=true — count members
3. Cross-reference with GET /subscribedSkus — verify capacity vs assignment
4. GET /groups/{id}/membersWithLicenseErrors — find failed assignments
5. Resolve errors: insufficient licenses, service plan conflicts, or missing usage location

Usage Report Endpoints Reference

Period values: D7, D30, D90, D180.

Pagination Handling

All list endpoints may return paginated results:

let allUsers = [];
let url = "/users?$select=assignedLicenses,signInActivity&$top=999&$count=true";

while (url) {
  const response = await client.api(url)
    .header("ConsistencyLevel", "eventual")
    .get();
  allUsers.push(...response.value);
  url = response["@odata.nextLink"] || null;
}

Important: $top max is 999 for user listing. Always follow @odata.nextLink for complete results.

Multi-Tenant (Lighthouse) Scanning

For MSPs scanning across customer tenants:

GET /tenantRelationships/managedTenants/tenants

Then for each tenant, authenticate via GDAP and run license scan queries.

Required GDAP Roles

Savings Calculation

Monthly savings = (inactive_count × license_monthly_cost) + (downgrade_count × savings_per_downgrade)
Annual savings = monthly_savings × 12

Required Permissions

Error Handling

License Assignment Error States

OData Filter Reference

Important Notes

• signInActivity requires Azure AD Premium P1 license on the tenant
• Usage reports have a 48-hour data lag — do not use for real-time decisions
• Disabled accounts with licenses are the easiest win — remove licenses immediately
• E5 license includes many sub-services — check each before recommending E3 downgrade
• CSP license changes take effect at next billing cycle
• Group-based licensing requires Azure AD Premium P1
• Maximum 999 users per $top parameter — always paginate

Progressive Disclosure — Reference Files