Manage product entitlements from a service

If you have a catalog of apps and add-ons, you can use the Microsoft Store collection API and Microsoft Store purchase API to access entitlement information for these products from your services. An entitlement represents a customer's right to use an app or add-on that is published through the Microsoft Store.

These APIs consist of REST methods that are designed to be used by developers with add-on catalogs that are supported by cross-platform services. These APIs enable you to do the following:

• Microsoft Store collection API: Query for products owned by a user and report a consumable product as fulfilled.
• Microsoft Store purchase API: Grant a free product to a user, get subscriptions for a user, and change the billing state of a subscription for a user.

Note

The Microsoft Store collection API and purchase API use The Microsoft identity platform (Entra ID) authentication to access customer ownership information. To use these APIs, you (or your organization) must have an Entra ID tenant and you must have Global administrator permission for the tenant. If you already use Microsoft 365 or other business services from Microsoft, you already have Entra ID tenant.

The Microsoft.StoreServices library

To help streamline the authentication flow and calling the Microsoft Store Services, review the Microsoft.StoreServices project and sample on Github. The Microsoft.StoreServices library will help manage the authentication keys and provides wrapper API's to call into the Microsoft Store Services for managing products. The sample project highlights how a service can use the Microsoft.StoreServices library, example logic for managing consumable products, reconciling refunded purchases, renew expired credentials, and more. A step-by-step configuration guide is included with the sample to setup the sample service on your PC or through Azure.

• Microsoft.StoreServices library (GitHub)
• Microsoft.StoreServices Sample (GitHub)

Overview

The following steps describe the end-to-end process for using the Microsoft Store collection API and purchase API:

1. Configure an application in Entra ID.
2. Associate your Entra ID application ID with your app in Partner Center.
3. In your service, create Entra ID access tokens that represent your publisher identity.
4. In your client Windows app, create a Microsoft Store ID key that represents the identity of the current user, and pass this key back to your service.

This end-to-end process involves two software components that perform different tasks:

• Your service. This is an application that runs securely in the context of your business environment, and it can be implemented using any development platform you choose. Your service is responsible for creating the Entra ID access tokens needed for the scenario and for calling the REST URIs for the Microsoft Store collection API and purchase API.
• Your client Windows app. This is the app for which you want to access and manage customer entitlement information (including add-ons for the app). This app is responsible for creating the Microsoft Store ID keys you need to call the Microsoft Store collection API and purchase API from your service.

Step 1: Configure an application in Entra ID

Before you can use the Microsoft Store collection API or purchase API, you must create an Entra ID Web application, retrieve the tenant ID and application ID for the application, and generate a key. The Entra ID Web application represents the service from which you want to call the Microsoft Store collection API or purchase API. You need the tenant ID, application ID and key to generate Entra ID access tokens that you need to call the API.

1. If you haven't done so already, follow the instructions in Quickstart: Register an application with the Microsoft identity platform to register a Web app / API application with Entra ID.

   Note

   When you register your application, you must choose Web app / API as the application type so that you can retrieve a key (also called a client secret) for your application. In order to call the Microsoft Store collection API or purchase API, you must provide a client secret when you request an access token from Entra ID in a later step.

2. In the Azure Management Portal, navigate to Microsoft Entra ID. Select your tenant, click App registrations in the left navigation pane under Manage, and then select your application.

3. You are taken to the application's main registration page. On this page, copy the Application ID value for use later.

4. Create a key that you will need later (this is all called a client secret). In the left pane, click Settings and then Keys. On this page, complete the steps to create a key. Copy this key for later use.

Step 2: Associate your Entra ID application ID with your client app in Partner Center

Before you can use the Microsoft Store collection API or purchase API to configure the ownership and purchases for your app or add-on, you must associate your Entra application ID with the app (or the app that contains the add-on) in Partner Center.

Note

You only need to perform this task one time. After you have your tenant ID, application ID and client secret, you can reuse these values any time you need to create a new Entra ID access token.

1. Sign in to Partner Center and select your app.
2. Go to the Services > Product collections and purchases page and enter your Entra application ID into one of the available Client ID fields.

Step 3: Create Entra ID access tokens

Before you can retrieve a Microsoft Store ID key or call the Microsoft Store collection API or purchase API, your service must create several different Entra ID access tokens that represent your publisher identity. Each token will be used with a different API. The lifetime of each token is 60 minutes, and you can refresh them after they expire.

Important

Create Entra ID access tokens only in the context of your service, not in your app. Your client secret could be compromised if it is sent to your app.

Understanding the different tokens and audience URIs

Depending on which methods you want to call in the Microsoft Store collection API or purchase API, you must create either two or three different tokens. Each access token is associated with a different audience URI.

• In all cases, you must create a token with the https://onestore.microsoft.com audience URI. In a later step, you will pass this token to the Authorization header of methods in the Microsoft Store collection API or purchase API.

  Important

  Use the https://onestore.microsoft.com audience only with access tokens that are stored securely within your service. Exposing access tokens with this audience outside your service could make your service vulnerable to replay attacks.

• If you want to call a method in the Microsoft Store collection API to query for products owned by a user or report a consumable product as fulfilled, you must also create a token with the https://onestore.microsoft.com/b2b/keys/create/collections audience URI. In a later step, you will pass this token to a client method in the Windows SDK to request a Microsoft Store ID key that you can use with the Microsoft Store collection API.

• If you want to call a method in the Microsoft Store purchase API to grant a free product to a user, get subscriptions for a user, or change the billing state of a subscription for a user, you must also create a token with the https://onestore.microsoft.com/b2b/keys/create/purchase audience URI. In a later step, you will pass this token to a client method in the Windows SDK to request a Microsoft Store ID key that you can use with the Microsoft Store purchase API.

Create the tokens

To create the access tokens, use the OAuth 2.0 API in your service by following the instructions in Service to Service Calls Using Client Credentials to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. Here is a sample request.

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://onestore.microsoft.com

For each token, specify the following parameter data:

• For the client_id and client_secret parameters, specify the application ID and the client secret for your application that you retrieved from the Azure Management Portal. Both of these parameters are required in order to create an access token with the level of authentication required by the Microsoft Store collection API or purchase API.

• For the resource parameter, specify one of the audience URIs listed in the previous section, depending on the type of access token you are creating.

After your access token expires, you can refresh it by following the instructions here. For more details about the structure of an access token, see Supported Token and Claim Types.

Step 4: Create a Microsoft Store ID key

Before you can call any method in the Microsoft Store collection API or purchase API, your app must create a Microsoft Store ID key and send it to your service. This key is a JSON Web Token (JWT) that represents the identity of the user whose product ownership information you want to access. For more information about the claims in this key, see Claims in a Microsoft Store ID key.

Currently, the only way to create a Microsoft Store ID key is by calling a Universal Windows Platform (UWP) API from client code in your app. The generated key represents the identity of the user who is currently signed in to the Microsoft Store on the device.

Note

Each Microsoft Store ID key is valid for 30 days. Before the key expires, you can renew the key. We recommend that you renew your Microsoft Store ID keys rather than creating new ones.

To create a Microsoft Store ID key for the Microsoft Store collection API

Follow these steps to create a Microsoft Store ID key that you can use with the Microsoft Store collection API to query for products owned by a user or report a consumable product as fulfilled.

1. Pass the Entra ID access token that has the audience URI value https://onestore.microsoft.com/b2b/keys/create/collections from your service to your client app. This is one of the tokens you created earlier in step 3.

2. In your app code, call one of these methods to retrieve a Microsoft Store ID key:

• If your app uses the StoreContext class in the Windows.Services.Store namespace to manage in-app purchases, use the StoreContext.GetCustomerCollectionsIdAsync method.

• If your app uses the CurrentApp class in the Windows.ApplicationModel.Store namespace to manage in-app purchases, use the CurrentApp.GetCustomerCollectionsIdAsync method.

  Pass your Entra ID access token to the serviceTicket parameter of the method. If you maintain anonymous user IDs in the context of services that you manage as the publisher of the current app, you can also pass a user ID to the publisherUserId parameter to associate the current user with the new Microsoft Store ID key (the user ID will be embedded in the key). Otherwise, if you don't need to associate a user ID with the Microsoft Store ID key, you can pass any string value to the publisherUserId parameter.

3. After your app successfully creates a Microsoft Store ID key, pass the key back to your service.

To create a Microsoft Store ID key for the Microsoft Store purchase API

Follow these steps to create a Microsoft Store ID key that you can use with the Microsoft Store purchase API to grant a free product to a user, get subscriptions for a user, or change the billing state of a subscription for a user.

1. Pass the Entra ID access token that has the audience URI value https://onestore.microsoft.com/b2b/keys/create/purchase from your service to your client app. This is one of the tokens you created earlier in step 3.

2. In your app code, call one of these methods to retrieve a Microsoft Store ID key:

• If your app uses the StoreContext class in the Windows.Services.Store namespace to manage in-app purchases, use the StoreContext.GetCustomerPurchaseIdAsync method.

• If your app uses the CurrentApp class in the Windows.ApplicationModel.Store namespace to manage in-app purchases, use the CurrentApp.GetCustomerPurchaseIdAsync method.

  Pass your Entra ID access token to the serviceTicket parameter of the method. If you maintain anonymous user IDs in the context of services that you manage as the publisher of the current app, you can also pass a user ID to the publisherUserId parameter to associate the current user with the new Microsoft Store ID key (the user ID will be embedded in the key). Otherwise, if you don't need to associate a user ID with the Microsoft Store ID key, you can pass any string value to the publisherUserId parameter.

3. After your app successfully creates a Microsoft Store ID key, pass the key back to your service.

Diagram

The following diagram illustrates the process of creating a Microsoft Store ID key.

Claims in a Microsoft Store ID key

A Microsoft Store ID key is a JSON Web Token (JWT) that represents the identity of the user whose product ownership information you want to access. When decoded using Base64, a Microsoft Store ID key contains the following claims.

• iat:   Identifies the time at which the key was issued. This claim can be used to determine the age of the token. This value is expressed as epoch time.
• iss:   Identifies the issuer. This has the same value as the aud claim.
• aud:   Identifies the audience. Must be one of the following values: https://collections.mp.microsoft.com/v6.0/keys or https://purchase.mp.microsoft.com/v6.0/keys.
• exp:   Identifies the expiration time on or after which the key will no longer be accepted for processing anything except for renewing keys. The value of this claim is expressed as epoch time.
• nbf:   Identifies the time at which the token will be accepted for processing. The value of this claim is expressed as epoch time.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId:   The client ID that identifies the developer.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload:   An opaque payload (encrypted and Base64 encoded) that contains information that is intended only for use by Microsoft Store services.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId:   A user ID that identifies the current user in the context of your services. This is the same value you pass into the optional publisherUserId parameter of the method you use to create the key.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri:   The URI that you can use to renew the key.

Here is an example of a decoded Microsoft Store ID key header.

{
    "typ":"JWT",
    "alg":"RS256",
    "x5t":"agA_pgJ7Twx_Ex2_rEeQ2o5fZ5g"
}

Here is an example of a decoded Microsoft Store ID key claim set.

{
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId": "1d5773695a3b44928227393bfef1e13d",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload": "ZdcOq0/N2rjytCRzCHSqnfczv3f0343wfSydx7hghfu0snWzMqyoAGy5DSJ5rMSsKoQFAccs1iNlwlGrX+/eIwh/VlUhLrncyP8c18mNAzAGK+lTAd2oiMQWRRAZxPwGrJrwiq2fTq5NOVDnQS9Za6/GdRjeiQrv6c0x+WNKxSQ7LV/uH1x+IEhYVtDu53GiXIwekltwaV6EkQGphYy7tbNsW2GqxgcoLLMUVOsQjI+FYBA3MdQpalV/aFN4UrJDkMWJBnmz3vrxBNGEApLWTS4Bd3cMswXsV9m+VhOEfnv+6PrL2jq8OZFoF3FUUpY8Fet2DfFr6xjZs3CBS1095J2yyNFWKBZxAXXNjn+zkvqqiVRjjkjNajhuaNKJk4MGHfk2rZiMy/aosyaEpCyncdisHVSx/S4JwIuxTnfnlY24vS0OXy7mFiZjjB8qL03cLsBXM4utCyXSIggb90GAx0+EFlVoJD7+ZKlm1M90xO/QSMDlrzFyuqcXXDBOnt7rPynPTrOZLVF+ODI5HhWEqArkVnc5MYnrZD06YEwClmTDkHQcxCvU+XUEvTbEk69qR2sfnuXV4cJRRWseUTfYoGyuxkQ2eWAAI1BXGxYECIaAnWF0W6ThweL5ZZDdadW9Ug5U3fZd4WxiDlB/EZ3aTy8kYXTW4Uo0adTkCmdLibw=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId": "infusQMLaYCrgtC0d/SZWoPB4FqLEwHXgZFuMJ6TuTY=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri": "https://collections.mp.microsoft.com/v6.0/b2b/keys/renew",
    "iat": 1733526889,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1733523289,
    "nbf": 1736118889
}

Related topics

• Query for products
• Report consumable products as fulfilled
• Grant free products
• Get subscriptions for a user
• Change the billing state of a subscription for a user
• Renew a Microsoft Store ID key
• Integrating Applications with the Microsoft identity platform
• ID tokens in the Microsoft identity platform
• Microsoft.StoreServices library (GitHub)