DocumentationPrimetimePrimetime Digital Rights Management Help

PlayReady license token request / response playready-license-token-request-response

Last update: Mon Oct 02 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

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:

    code language-none 
    <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:

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

Request Query Parameters section_26F8856641A64A46A3290DBE61ACFAD2

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

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 section_0079C31B4AF14DBBB6277CF251FB90E3

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
recommendation-more-help
6586e0f0ff95af3ee5405884