Manage product entitlements from a service

If you have a catalog of apps and add-ons, you can use the Windows Store collection API and Windows 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 Windows 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:

Note

The Windows 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 Office 365 or other business services from Microsoft, you already have Azure AD directory.

Overview

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

  1. Configure a Web application in Azure AD.
  2. Associate your Azure AD client ID with your application in the Windows Dev Center dashboard.
  3. In your service, create Azure AD access tokens that represent your publisher identity.
  4. In client-side code in your Windows app, create a Windows Store ID key that represents the identity of the current user, and pass the Windows Store ID key back to your service.
  5. After you have the required Azure AD access token and Windows Store ID key, call the Windows Store collection API or purchase API from your service.

The following sections provide more details about each of these steps.

Step 1: Configure a Web application in Azure AD

Before you can use the Windows Store collection API or purchase API, you must create an Azure AD Web application, retrieve the tenant ID and client ID for the application, and generate a key. The Azure AD application represents the app or service from which you want to call the Windows Store collection API or purchase API. You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

Note

You only need to perform the tasks in this section one time. After you update your Azure AD application manifest and you have your tenant ID, client ID and client secret, you can reuse these values any time you need to create a new Azure AD access token.

  1. Follow the instructions in Integrating Applications with Azure Active Directory to add a Web application to Azure AD.

    Note

    On the Tell us about your application page, make sure that you choose Web application and/or web API. This is required so that you can retrieve a key (also called a client secret) for your application. In order to call the Windows 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 Active Directory. Select your directory, click the Applications tab at the top, and then select your application.

  3. Click the Configure tab. On this tab, obtain the client ID for your application and request a key (this is called a client secret in later steps).
  4. At the bottom of the screen, click Manage manifest. Download your Azure AD application manifest and replace the "identifierUris" section with the following text.

    "identifierUris" : [                                
            "https://onestore.microsoft.com",
            "https://onestore.microsoft.com/b2b/keys/create/collections",
            "https://onestore.microsoft.com/b2b/keys/create/purchase"
        ],
    

    These strings represent the audiences supported by your application. In a later step, you will create Azure AD access tokens that are associated with each of these audience values. For more information about how to download your application manifest, see Understanding the Azure Active Directory application manifest.

  5. Save your application manifest and upload it to your application in the Azure Management Portal.

Step 2: Associate your Azure AD client ID with your app in Windows Dev Center

Before you can use the Windows Store collection API or purchase API to operate on an app or add-on, you must associate your Azure AD client ID with the app (or the app that contains the add-on) in the Dev Center dashboard.

Note

You only need to perform this task one time.

  1. Sign in to the Dev Center dashboard and select your app.
  2. Go to the Services > Product collections and purchases page and enter your Azure AD client ID into one of the available fields.

Step 3: Create Azure AD access tokens

Before you can retrieve a Windows Store ID key or call the Windows 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 Windows 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 (these are the same URIs that you previously added to the "identifierUris" section of the Azure AD application manifest).

  • 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 Windows 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 Windows 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 Windows Store ID key that you can use with the Windows Store collection API.

  • If you want to call a method in the Windows 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 Windows Store ID key that you can use with the Windows 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 client 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 Windows 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 Windows Store ID key

Before you can call any method in the Windows Store collection API or purchase API, your app must create a Windows 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 Windows Store ID key.

Currently, the only way to create a Windows 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 Windows Store on the device.

Note

Each Windows Store ID key is valid for 90 days. After a key expires, you can renew the key. We recommend that you renew your Windows Store ID keys rather than creating new ones.

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

Follow these steps to create a Windows Store ID key that you can use with the Windows 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 you created with the https://onestore.microsoft.com/b2b/keys/create/collections audience URI from your service to your client app.

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

    Pass your Azure AD access token to the serviceTicket parameter of the method. You can optionally pass an ID to the publisherUserId parameter that identifies the current user in the context of your services. If you maintain user IDs for your services, you can use this parameter to correlate these user IDs with the calls you make to the Windows Store collection API.

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

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

Follow these steps to create a Windows Store ID key that you can use with the Windows 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 you created with the https://onestore.microsoft.com/b2b/keys/create/purchase audience URI from your service to your client app.

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

    Pass your Azure AD access token to the serviceTicket parameter of the method. You can optionally pass an ID to the publisherUserId parameter that identifies the current user in the context of your services. If you maintain user IDs for your services, you can use this parameter to correlate these user IDs with the calls you make to the Windows Store purchase API.

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

Step 5: Call the Windows Store collection API or purchase API from your service

After your service has a Windows Store ID key that enables it to access a specific user's product ownership information, your service can call the Windows Store collection API or purchase API by following these instructions:

For each scenario, pass the following information to the API:

  • The Azure AD access token that you created earlier with the https://onestore.microsoft.com audience URI. This token represents your publisher identity. Pass this token in the request header.
  • The Windows Store ID key you retrieved from client-side code in your app. This key represents the identity of the user whose product ownership information you want to access.

Claims in a Windows Store ID key

A Windows 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 Windows 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 Windows 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 Windows Store ID key header.

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

Here is an example of a decoded Windows 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
}