App License Schema
Updated: November 13, 2012
Learn about the elements and attributes of the app license schema, which defines the string that specifies validity and usage properties in app licenses.
Applies to: SharePoint Server 2013 | SharePoint Foundation 2013 | Office 2013 | Project 2013
The following app license schema defines the structure that specifies usage properties in app licenses. If your app includes license validation checks, use this schema to create test licenses to test the license validation code in your app. For more information, see How to: Add license checks to your apps for Office and How to: Add license checks to your app for SharePoint.
Use the VerifyEntitlementToken method of the Office Store verification web service to determine if an app license is valid. The VerifyEntitlementToken method takes a app license token as a parameter, and returns an VerifyEntitlementTokenResponse that contains the license token properties, including whether or not the license token is valid.
To support app license testing, the Office Store verification web service does not validate the encryption token or any of the attribute values of license tokens where the test attribute is set to true. However, the service does interpret the token, and all the properties of the VerifyEntitlementTokenResponse object returned by the service can be read.
<r>
<t
aid="{2[A-Z] 8-12[0-9]}"
pid="{GUID}"
cid="{16[0-H]}"
did="{GUID}"
ts="Integer"
et="Free" |"Trial" | "Paid"
sl="true | 1" | "false| 0"
ad="UTC"
ed="UTC"
sd="UTC"
te="UTC"
test="true | 1" | "false | 0"/>
<d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
</r>
Elements
r
Required. The root element.
t
Required. Contains attributes that represent various properties of the app license.
Attributes
Attribute | Description |
|---|---|
aid | Required text. The asset ID assigned to this app by the Office Store. |
pid | Required text. The GUID that represents the product ID of the app. The product ID of the app is specified in the app manifest. |
cid | Required text. Represents the purchaser ID. This is an encrypted value of the Microsoft account used by the purchaser of the app. |
did | GUID that represents the deployment ID of the SharePoint deployment to which this app license applies. This attribute does not apply to apps for Office. For test licenses for apps for SharePoint, you don't need to specify the deployment ID in the app license XML. The ImportAppLicense method supplies the correct deployment ID to the license token XML. |
ts | Integer representing the total number of users licensed to access this app, by this purchaser. For apps that are site licensed, this value is 0. This attribute does not apply to apps for Office. |
et | Required text. Enumeration that represents the type of app license. Valid values include Free, Paid, and Trial. |
ad | Required text. UTC time-date stamp that represents the acquisition date for the app license. |
sl | Boolean value that represents whether the app license is a site license. This attribute is optional for app licenses that are not site licenses. This attribute does not apply to apps for Office. |
ed | Optional text. UTC time-date stamp that represents the expiration date for the app license. This value can be used to check if the trial license is expired. |
sd | Required text. UTC time-date stamp that represents one of the following:
|
te | Required text. UTC time-date stamp that represents the date the current app license token expires. |
test | Optional Boolean value. Represents whether the app license is a test license. |
d
Required. Encryption token used by the Office Store verification service to determine whether the app license token is valid. This is an encrypted signature derived from the literal string contained in the <t> element.
When you submit a test app license token to the Office Store verification web service, the service does not perform that validation check of comparing the encrypted signature in the <d> element to the string contained in the <t> element.
Remarks
 Important |
|---|
When your app receives an app license token from its hosting environment, be it an Office application or SharePoint, developers are advised not to parse or otherwise manipulate the app license token string before passing it to the Office Store verification web service for verification. While the app license token is structured as an XML fragment, for purposes of validation the Office Store verification web service treats the token as a literal string. The Office Store verification web service compares the contents of the <t> element to the value of the <d> element, which is an encrypted signature derived from the literal string contained in the <t> element. Any reformatting of the license token, such as adding white space, tabs, line breaks, etc., will change the literal value of the <t> element and therefore cause the license verification check to fail. When you submit a test app license token to the Office Store verification web service, the service does not perform that validation check of comparing the encrypted signature in the <d> element to the string contained in the <t> element. This enables developers to create their own test app license tokens for testing purposes without worrying about formatting, or generating the encryption signature for the <d> element. |
Code example: App license XML for an app for SharePoint
The following example is the app license XML for an app for SharePoint, representing a trial app for which the purchaser has acquired 30 seats.
<r>
<t
aid="WA900006056"
pid="{4FB601F2-5469-4542-B9FC-B96345DC8B39}"
cid="32F3E7FC559F4F49"
did="{0672BAE9-B41B-48FE-87F1-7F4D3DD3F3B1}"
ts="30"
et="Trial"
ad="2012-01-12T21:58:13Z"
ed="2012-06-30T21:58:13Z"
sd="2012-01-12T00:00:00Z"
te="2012-06-30T02:49:34Z" />
<d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
</r>
Date | Description |
|---|---|
November 13, 2012 | Added information on how the verification web service treats the app license token as a literal string for validation purposes. |
October 09, 2012 | Corrected value formatting for sl and et attributes. |
July 16, 2012 | Initial publication |
