ISV app license management for SaaS offers

  • Article

If you enabled license management for your SaaS offers (currently available for AppSource only) in Partner Center, then you must integrate with usageRights Graph API to look up licenses of customers. You use usageRights API to determine the licensing state of the customer calling your solution so you can act accordingly.

Important

Azure Active Directory (Azure AD) Graph is deprecated as of June 30, 2023. Going forward, we're making no further investments in Azure AD Graph. Azure AD Graph APIs have no SLA or maintenance commitment beyond security-related fixes. Investments in new features and functionalities will only be made in Microsoft Graph.

We'll retire Azure AD Graph in incremental steps so that you have sufficient time to migrate your applications to Microsoft Graph APIs. At a later date that we will announce, we will block the creation of any new applications using Azure AD Graph.

To learn more, see Important: Azure AD Graph Retirement and Powershell Module Deprecation.

usageRights API

API: usageRight resource type

How to use usageRights API

You can call usageRights Graph API to determine what is the state of the license for the logged-in user who purchased the subscription of your offer. To call the API, follow these steps:

  1. Get user On Behalf Of token: see get access on behalf of a user
  2. Call Graph to get user's object ID: see use the Microsoft Graph API
  3. Call usageRights API to determine the user has License to the plan: see list user usageRights

Note

You need to have minimum User.Read permissions to call usageRights. The usageRights API is currently in beta version. After the version is updated to V1, ISVs should upgrade from beta to V1 version when available.

Response Codes

Code 200 with response body:

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('ea201692-eb91-44e0-b82a-9dd4c78ced32')/usageRights",
    "@odata.nextLink": "https://graph.microsoft.com/beta/users/ea201692-eb91-44e0-b82a-9dd4c78ced32/usageRights?$skiptoken=ZXlKamIzTnRiM05FWWxSdmEyVnVJam9pVzN0Y0ltTnZiWEJ2YzJsMFpWUnZhMlZ1WENJNmUxd2lkRzlyWlc1Y0lqcHVkV3hzTEZ3aWNtRnVaMlZjSWpwN1hDSnRhVzVjSWpwY0lqRkdSa1pHUmtaR1JrWkdSa1pHUmtaR1JrWkdSa1pHUmt.......",
    "value": [
        {
            "id": "635991be-b7a3-4dd4-a48c-f1d39732fe94",
            "catalogId": "ID of the Product",
            "serviceIdentifier": "ISV friendly ID of the product, this is same as planID in partner center",
            "state": "active"
        }
    ]
}

API response explained

  • Odata.nextLink: If your request has several results and needs to be paged, Odata.nextLink is in the response. You can use this to page the results until no more Odata.nextLink values appear, which indicates the end of the response.
  • serviceIdentifier: The planId of the plan that customer purchased.
  • state: The state of the license. You can see all possible values of state in the usageRights API documentation. Typically, the user should be able to run your solution if the license state is active or warning. Any other state means user's subscription isn't in good condition either because it expired, is suspended for nonpayment, etc.
  • Code 200 with empty response: This is likely because the customer doesn't have a license assigned.
  • Code 400 Bad request: This is likely because of missing fields while calling the API like Bearer token. Check your API call parameters.
  • Code 403 Forbidden: This is likely because of expired or unauthorized token. Verify that you're using the right Microsoft Entra App to authenticate the usageRights Graph API.
  • Code 500 Internal server error: Retry the API call. If the error persists, contact Microsoft Support.

Note

If the Microsoft Entra app you use for SaaS fulfillment API is also used for usageRights API, ensure that the tenant under which the add app is created is either the publishing tenant OR associated tenant in partner center.

Use the following steps to determine the tenant that Microsoft Entra App is created under is part of the partner center setup:

  1. Log in to Microsoft Partner Center with the publisher account that is used to publish the SaaS offer.
  2. Under settings link on right top corner, select "Account settings" and then "tenants"
  3. You can see all tenants associated in the Microsoft AI Cloud Partner Program account.
  4. The tenant that is the owner of the Microsoft Entra App should be on this list.
  5. If the tenant isn't on the list, you can use the "Associate Azure ID" button to link the tenant.