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 Azure Active Directory (Azure AD) authentication to access customer ownership information. To use these APIs, you (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. If you already use Microsoft 365 or other business services from Microsoft, you already have Azure AD directory.

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 Azure AD.
2. Associate your Azure AD application ID with your app in Partner Center.
3. In your service, create Azure AD 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 Azure AD 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 Azure AD

Before you can use the Microsoft Store collection API or purchase API, you must create an Azure AD Web application, retrieve the tenant ID and application ID for the application, and generate a key. The Azure AD 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 Azure AD access tokens that you need to call the API.

1. If you haven't done so already, follow the instructions in Integrating Applications with Azure Active Directory to register a Web app / API application with Azure AD.

   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 Azure AD in a later step.

2. In the Azure Management Portal, navigate to Azure Active Directory. Select your directory, click App registrations in the left navigation pane, 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 Azure AD 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 Azure AD 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 Azure AD 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 Azure AD application ID into one of the available Client ID fields.

Step 3: Create Azure AD 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 Azure AD 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 Azure AD 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 90 days. After a 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 Azure AD 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 Azure AD 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 Azure AD 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 Azure AD 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": 1442395542,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1450171541,
    "nbf": 1442391941
}

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 Azure Active Directory
• Understanding the Azure Active Directory application manifest
• Supported Token and Claim Types
• Microsoft.StoreServices library (GitHub)