PlayReady license token request / response

The PlayReady license token interface provides production and test services.

This HTTP request returns a token that can be redeemed for a PlayReady license.

Method: GET, POST (with a www-url-encoded body that contains parameters for both methods)

URLs:

Production: https://pr-gen.{prod_domain}/hms/pr/token
Test: [https://pr-gen.test.expressplay.com/hms/pr/token](https://pr-gen.test.expressplay.com/hms/pr/token)

Sample request:

<xref href="https: pr-gen.test.expressplay.com="" hms="" pr="" token?customerAuthenticator="201722,1ad8eed133edf43cbcc185f0236828ae&kid=b366360da82e9c6e0b0984002a362cf2&contentKey=b366360da82e9c6e0b0984002a362cf2&rightsType=BuyToOwn&analogVideoOPL=0&compressedDigitalAudioOPL=0&compressedDigitalVideoOPL=0&uncompressedDigitalAudioOPL=0&uncompressedDigitalVideoOPL=0&quot; format=&quot;html&quot; scope=&quot;external&quot;">
https://pr-gen.test.expressplay.com/hms/pr/token?customerAuthenticator=
 <ExpressPlay customer authenticator identifier>
 &kid=<CEKSID>
 &contentKey=<CEK>
 &rightsType=BuyToOwn
 &analogVideoOPL=0
 &compressedDigitalAudioOPL=0
 &compressedDigitalVideoOPL=0
 &uncompressedDigitalAudioOPL=0
 &uncompressedDigitalVideoOPL=0
</xref href="https:>

Sample Response:

{"licenseAcquisitionUrl":"https://expressplay-licensing.axprod.net/LicensingService.ashx",
            "token":"<base64-encoded ExpressPlay token>"}

Request Query Parameters

Table 9: Token Query Parameters

Query Parameter	Description	Required?
customerAuthenticator	This is your customer API key, one each for your production and test environments. You can find this on the ExpressPlay Admin Dashboard tab.	Yes
errorFormat	Either html or json. If html (the default) an HTML representation of any errors is provided in the entity body of the response. If json is specified, a structured response in JSON format is returned. See JSON Errors for details. The mime type of the response is either text/uri-list on success, text/html for HTML error format, or application/json for JSON error format.	No

Query Parameter

Description

Required?

customerAuthenticator

This is your customer API key, one each for your production and test environments. You can find this on the ExpressPlay Admin Dashboard tab.

Yes

errorFormat

Either html or json. If html (the default) an HTML representation of any errors is provided in the entity body of the response.

If json is specified, a structured response in JSON format is returned. See JSON Errors for details.

The mime type of the response is either text/uri-list on success, text/html for HTML error format, or application/json for JSON error format.

Table 10: License Query Parameters

Query Parameter	Description	Required?
generalFlags	A 4 byte hexadecimal string representing the license flags. It must be set to ‘00000001' for a persistent license. Note: Rental licenses ( rightsType=Rental) MUST be persistent.	No
kek	Key Encryption Key (KEK). Keys are stored encrypted with a KEK using a key wrapping algorithm (AES Key Wrap, RFC3394).	No
kid	A 16 byte hexadecimal string representation of the content encryption key or a string ^somestring'. The length of the string followed by the '^' cannot be greater than 64 characters.	Yes
ek	A hex string representation of the encrypted content key.	No
contentKey	A 16 byte hexadecimal string representation of the content encryption key	Yes, unless kek and ek or kid are provided
rightsType	Specifies the kind of rights. Must be BuyToOwn or Rental.	Yes
rental.periodEndTime	Rental end date. This value MUST be in the ‘RFC 3339' _ date/time format in the ‘Z' zone designator ("Zulu time") format, or an integer preceded by a '+' sign. If the value is a RFC 3339 date/time format, then it represents an absolute expiration date/time for the license. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is an integer preceded by a '+' sign, it is taken as a relative number of seconds from the time the token is issued. The content cannot be played after this time. Only valid if rightsType is Rental.	Yes, when rightsType is Rental.
rental.playDuration	Time, in seconds, that the content can be played once play has started. Only valid if rightsType is Rental.	No
analogVideoOPL	Integer value to indicate the Output Protection Level for analog video. Valid range 0-999.	Yes
compressedDigitalAudioOPL	Integer value to indicate the Output Protection Level for compressed digital audio. Valid range 0-999.	Yes
compressedDigitalVideoOPL	Integer value to indicate the Output Protection Level for compressed digital video. Valid range 0-999.	Yes
uncompressedDigitalAudioOPL	Integer value to indicate the Output Protection Level for uncompressed digital audio. Valid range 0-999.	Yes
uncompressedDigitalVideoOPL	Integer value to indicate the Output Protection Level for uncompressed digital video. Valid range 0-999.	Yes
unknownOutputBehavior	Required behaviour when the output is unknown. Allowed values: Allow, Disallow or SDOnly	No
outputControlFlags	A 4-byte hex value to indicate the flags for other output control options	No
extensionType	An arbitrary 4-letter word representing a 32-bit identifier for an Extension. Each letter's 8-bit ASCII code is the corresponding 8-bit byte portion of the identifier. For example, the identifier value 0x61626364 (hexadecimal) would be written ‘ abcd', because the ASCII code for ‘a' is 0x61, etc.	No
extensionPayload	A base64 encoded string of the Extension.	Yes, when extensionType is specified.

Responses

Table 11: HTTP Responses

HTTP Status Code	Description	Content-Type	Entity Body Contains
`200 OK`	No error.	`text/uri-list`	License acquisition url and token
`400 Bad Request`	Invalid args	`text/html` or `application/json`	Error description
`401 Unauthorized`	Auth failed	`text/html` or `application/json`	Error description
`404 Not found`	Bad URL	`text/html` or `application/json`	Error description
`50x Server Error`	Server error	`text/html` or `application/json`	Error description

Table 12: Event Error Codes

Code	Description
-2002	Invalid token expiration time: <details>
-2003	Invalid IP address
-2005	Invalid content encryption key: <details>
-2008	Invalid output control flags specified: <details>
-2017	Authentication token must be supplied
-2018	Authentication token invalid: <details> Note: This can happen if the authenticator is wrong or when accessing the test API at .test.expressplay.com using the production authenticator and vice versa. Note: The Test SDK and Advanced Test Tool (ATT) only work with .test.expressplay.com, whereas production devices must use *.service.expressplay.com.
-2019	Insufficient tokens available
-2020	Missing rights type
-2021	Invalid rights type
-2022	Missing rental period end time
-2023	Missing rental play duration
-2025	Invalid rental play duration
-2027	Content encryption key must be 32-hexadecimal digits long
-2030	ExpressPlay Admin error: <details>
-2031	Service Account Disabled
-2033	Invalid cookie
-2034	Invalid Output Control, values out of specified range
-2035	No corresponding value specified
-2036	Extension type should be 4 characters
-2037	Extension payload should be Base64 encoded
-2040	OutputControlFlag must be encode 4 bytes
-3004	Invalid error format specified: <format>
-4001	Device could not be authenticated
-4018	Missing kid
-4019	Failed to get content key from key storage service
-4020	kid must be 32 hexadecimal characters long
-4021	kid must be 64 characters long after the ^
-4022	Invalid kid
-4024	Invalid encrypted key or kek
-5001	Invalid unknown output type error
-5002	PlayReady option is disabled for this service
-5003	Invalid general flags
-5004	Device ID must be 32 hexadecimal characters long
-5005	Invalid device ID
-5006	Missing OPL value
-5007	Only one of kek or contentKey can be specified