Developer Center

REST API Documentation

1   Service Region Hosts

The production URLs throughout this documentation use a placeholder domain name {prod_domain} that should be replaced by the appropriate region-specific domain name as listed below. Note that your production URLs are also visible in the ExpressPlay Admin dashboard, reflecting the service region to which your service is bound. Also note that your ExpressPlay service is physically located in the datacenter of your region of choice, but your ExpressPlay service is not restricted to requests from that region.

PRODUCTION DOMAINS:
Europe:
service.expressplay.com
China:
service.expressplay.cn

Note: All request parameters are case-sensitive.

2   Record Retrieval

Purpose
Queries ExpressPlay for transaction logs for your service. Logs may be queried by one of four methods:
  1. The default, if nothing else is specified, returns the most recent 32 events.
  2. If a string ‘cookie’ is specified, the API returns the recent event matching this cookie. This may not be used in combination with other querying methods.
  3. If an integer ‘id’ is specified, the event matching the given id is returned. (See "event_id" below.)
  4. If integers ‘start’ and ‘length’ are specified, this API returns records matching that range. The parameter ‘start’ is the offset, and ‘length’ is the number of records returned, providing a window of records. This may be iteratively called to retrieve all known records. Note that ‘start’ does not refer to an event_id, but rather a 0-based index of all records for a service. To progressively obtain all records, a caller would request (start=0, length=200), then (start=200, length=200) and so forth until no more records are returned.
Using more than one method simultaneously in a request is unsupported.
URLs
Production:
https://api.{prod_domain}/cmiapi/getrecord/
Test:
https://api.test.expressplay.com/cmiapi/getrecord/
Method
GET

2.1   Request Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes
type Either "ms3" for MS3, "bb" for Broadband, "pr" for PlayReady, "fp" for FairPlay, "wv" for Widevine, "pt" for Primetime and "tls" for TLS. Records returned will be of this type Defaults to "ms3" if not specified. No
cookie The arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. If cookie parameter is specified, only one record is returned in the response. No
id Id of requested record. This is the event_id for ‘pr’ No
start Beginning of requested range. No
length Requested items in range. Only used if ‘start’ passed. Maximum of 200. No

2.3   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No lowlevel error application/json JSON result
404 Not found Bad URL text/html or application/json Error description
50x Server Error Server error text/html or application/json Error description

The response will be of Content-Type application/json.

2.4   JSON Contents

Parameter Description Optional?
valid Request was valid: the service was located and the customerAuthenticator was verified. No
error See below and JSON Errors for details. No
events This is only set if valid is ‘True’. This contains the list of found records. Note that this list may be empty if nothing was found. Yes

2.5   Events Fields for bb, ms3, fp, wv, pt and tls

Field Type Description
event_id string ExpressPlay-assigned string for this record.
type string Type of transaction. One of ‘ms3License’, ‘bbLicense’, ‘bbNodeAcquisition’, ‘bbLinkAcquisition’, ‘bbUnLink’, ‘fpLicense’, ‘wvLicense’, ‘ptLicense’ and ‘tlsLicense’
error_code integer Error code as determined by token redemption service (see below).
start_time datetime Date and time of transaction expressed in ISO 8601 format.
duration integer Duration of transaction in milliseconds.
device_id string Device id of the device redeeming the token.
cookie string The cookie provided during token generation.
expiration datetime Expiration time of this token expressed in ISO 8601 format.
rental_end_date datetime Expiration time of this rental expressed in ISO 8601 format. Can be null if this record is not a rental.
rental_end_seconds integer If rights type is rental, this may be positive. It represents the relative number of seconds from the time the license is issued that the license will be valid.
rental_play_duration integer Time, in seconds, that the content can be played once play has started.
token_id string Token identifier.
content_id string Only one ID is given, no matter how many were in content.
content_key_hash string Only one hash is given, no matter how many keys were in content.
device_id_binding string Device ID to which the token was bound.
bb_fault_code string Code of possible Broadband error.
bb_fault_string string Description of possible Broadband error.
control_flags hex string MS3 control flags.
output_control_value hex string MS3 or Broadband output control value.
output_control_flags hex string MS3 or Broadband output control flags.
transaction_account_name string transaction is counted against the service that obtained the token.
extension string This includes the extension_type, extension_critical_flag and extension payload separated by a comma. Only 64 char wide values are returned. If the number of characters are more than 64, only the first 30 and last 30 characters are returned.
extension_type string MS3 or FP extension type. Exists only in MS3 or FP token redemption, and only one type is given, no matter how many were in content.
extension_critical_flag string MS3 extension critical flag. Exists only in MS3 token redemption, and only one critical flag is given, no matter how many were in content.
extension_payload string MS3 or FP extension payload. Exists only in MS3 or FP token redemption, and only one payload is given, no matter how many were in content. Only 64 char wide values are returned. If the number of characters are more than 64, only the first 30 and last 30 characters are returned.
output_control_override_id string Broadband outputControlOverrideId. Only 64 char wide values are returned. If the number of characters are more than 64, only the first 30 and last 30 characters are returned.
output_control_override_parameter string Broadband outputControlOverrideParameter. Only 64 char wide values are returned. If the number of characters are more than 64, only the first 30 and last 30 characters are returned.
output_control_override_value integer Broadband outputControlOverrideValue.
output_control_obligation string Broadband outputControlObligation. Only 64 char wide values are returned. If the number of characters are more than 64, only the first 30 and last 30 characters are returned.
output_control_override string Broadband outputControlOverride. Only 64 char wide values are returned. If the number of characters are more than 64, only the first 30 and last 30 characters are returned.
express boolean true if transaction is from an Express client; false otherwise.
bundled boolean true if transaction is from a bundled Express client; false otherwise.
cfid string An 8 byte hexadecimal string reference to a manufacturer’s device super-encryption key used to encrypt the content key.
active_user_id string A string representation of an active user id that is at most 64 characters long
asset_owner string A string representation of an asset owner for a given content
client_ip string Client ip only if that information is available
client_os string Client OS as available from the client request
client_version string Client version as available from the client request
pt_content_security_flags JSON string securityFlags, drmLevel, runtimeLevel, analogOutputProtection and digitalOutputProtection values. Only applicable for ‘ptLicense’.

2.6   Events Fields for PlayReady

Field Type Description
timestamp date Date representing the time stamp of the event
service_id integer Service id associated with the account
key_id GUID Key id expressed as a globally unique identifier
device_id string A string representing the device id
device_security_level integer Integer to represent the device security level
ip_address string String to represent the ip address
cookie string The cookie provided during token generation.
event_id string The event_id of the PlayReady record
duration integer Duration of transaction in milliseconds.
type string Type of transaction: prLicense
min_cert_security_level integer Security Level (0-3000)

2.7   Event Error Codes

Code Description
-2030 ExpressPlay Admin Error
-2031 Service Account Disabled
-4001 Token could not be parsed
-4002 Token could not be authenticated
-4003 Error decrypting token contents
-4005 IP Address parse error
-4006 Device could not be authenticated
-4010 Invalid Token
-4011 Token Expired
-4012 Token cannot be redeemed from this IP Address
-4013 Token cannot be redeemed by this device
-4014 Token redemption disallowed
-4015 Device reported agent execution error

3   Record Retrieval By Time

Purpose
Queries ExpressPlay for transaction logs for your service for a given time period. Logs may be queried by one of these methods:
  1. startTime and endTime have to be provided. If page and size are not provided, by default it displays page 0 (first page) and 200 records per page.
  2. If integers ‘page’ and ‘size’ are specified, this API returns ‘size’ records of the page number specified. This may be iteratively called to retrieve all known records. Note that ‘page’ is a 0-based index.
URLs
Production:
https://api.{prod_domain}/cmiapi/getrecordbytime/
Test:
https://api.test.expressplay.com/cmiapi/getrecordbytime/
Method
GET

3.1   Request Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes
type Either "ms3" for MS3, "bb" for Broadband, "pr" for PlayReady, "fp" for FairPlay, "wv" for Widevine, "pt" for Primetime and "tls" for TLS. Records returned will be of this type Defaults to "ms3" if not specified. No
startTime The value MUST be a string in RFC 3339 _ date/time format in the ‘Z’ zone designator ("Zulu time"). An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. startTime shouldn’t greater than 30 days from current time. Yes
endTime The value MUST be a string in RFC 3339 _ date/time format in the ‘Z’ zone designator ("Zulu time"). An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. This time shouldn’t be greater than current time and less than startTime. Yes
page Page number. Defaults to page 0 (first page) Page is a 0-based index. No
size Requested items on each page. Defaults to 200 if not provided. Size is limited to 2000 records. No

3.2   Example Queries

Production:
https://api.{prod_domain}/cmiapi/getrecordbytime?customerAuthenticator=553,d31ab64f35724f69beb177f0c3d01e41a&type=ms3
Test:
https://api.test.expressplay.com/cmiapi/getrecordbytime?customerAuthenticator=553,d31cd34f35724f69beb177f0c3d01e41a&type=bb

3.3   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No lowlevel error application/json JSON result
404 Not found Bad URL text/html or application/json Error description
50x Server Error Server error text/html or application/json Error description

The response will be of Content-Type application/json. Refer to ‘Events Fields for bb, ms3, fp, wv, pt and tls’ and ‘Events fields for PlayReady’ tables for the events returned in the events list.

3.4   JSON Contents

Parameter Description Optional?
valid Request was valid: the service was located and the customerAuthenticator was verified. No
error See below and JSON Errors for details. No
events This is only set if valid is ‘True’. This contains the list of found records. Note that this list may be empty if nothing was found. Refer to ‘Events Fields for bb, ms3, fp, wv, pt and tls table for bb, ms3, fp, wv, pt and tls. Refer to table ‘Events fields for PlayReady’ for PlayReady Yes
page This is only set if valid is ‘True’. This contains the page information and the total records available. It will be empty if nothing was found. Yes

4   Archived Record Retrieval

Purpose
Queries ExpressPlay for transaction logs for your service for a given date.
URLs
Production:
https://api.{prod_domain}/cmiapi/getarchivedlog/
Test:
https://api.test.expressplay.com/cmiapi/getarchivedlog/
Method
GET

4.1   Request Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes
date The value must be a string in ISO 8601 calendar date format, example: 2017-01-21 Yes

4.2   Example Queries

Production:
https://api.{prod_domain}/cmiapi/getarchivedlog?customerAuthenticator=553,d31ab64f35724f69beb177f0c3d01e41a&date=2017-01-21
Test:
https://api.test.expressplay.com/cmiapi/getarchivedlog?customerAuthenticator=553,d31cd34f35724f69beb177f0c3d01e41a&date=2017-01-21

4.3   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No lowlevel error application/javascript Gzip JSON result
404 Not found Bad URL text/html or application/json  

The response will be of Content-Type application/javascript and compressed with gzip. Refer to ‘Events Fields for bb, ms3, fp, wv, pt and tls’ and ‘Events fields for PlayReady’ tables for the events returned in the events list.

5   MS3 Token Request

Purpose
Requests a token that can be redeemed by customer for an MS3 license. Returned token is in the form of an MS3 Compound URI.
URLs
Production:
https://ms3-gen.{prod_domain}/hms/ms3/token
Test:
https://ms3-gen.test.expressplay.com/hms/ms3/token
Method
GET, POST (with www-url-encoded body containing parameters for both the methods)

5.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

5.2   License Parameters

Query Parameter Description Required?

contentId

contentId.N

URI that identifies a content id. Any number of these can be provided, but a matching number of contentKey parameters must be provided. If a single content id is supplied, the parameter contentId can be used. If multiple content ids are supplied, the parameters should be named, contentId.0, contentId.1, etc. to match the corresponding contentKey.N parameters. Note that numbering is 0-based (the first content id should be contentId.0). Yes, unless kek and kid are provided

contentKey

contentKey.N

A hexadecimal string representation of the content key associated with the corresponding contentId. Any number of these can be provided, but a matching number of contentId parameters must be provided. If a single content key is supplied, the parameter contentKey can be used. If multiple content keys are supplied, the parameters should be named contentKey.0, contentKey.1, etc. to match the corresponding contentId.N parameters. Note that numbering is 0-based (the first content key should be contentKey.0). Yes, unless kek and ek/ kid are provided
kek Key Encryption Key. Keys are stored encrypted with a KEK using a key wrapping algorithm (AES Key Wrap, RFC3394). If kek is supplied, either one of kid or ek needs to be supplied and not both. In both the cases, contentId needs to be provided. No

kid

kid.N

A unique 16 byte key id or a string ‘^somestring’ . The length of the string followed by the ‘^’ cannot be greater than 64 characters. Any number of these can be provided. If a single kid is supplied, the parameter kid can be used. If multiple key ids are supplied, the parameters are to be named, kid.0, kid.1, etc. Note that the numbering is 0-based (the first key id should be kid.0). These have to match the number of content ids. If kid is passed as a ‘^somestring’, kid is simply computed as the truncated SHA1 hash of the string. Check the note below for an example. No

ek

ek.N

A hex string representation of the encrypted content key associated with the corresponding contentId. Any number of these can be provided, but a matching number of contentId parameters must be provided. If a single encrypted content key is supplied, the parameter ek can be used. If multiple keys are supplied, the parameters should be named ek.0, ek.1, etc. to match the corresponding contentId.N parameters. Note that numbering is 0-based (the first encrypted content key should be ek.0). No
contentURL Content URL. See note below regarding its treatment as a template. Yes
contentUrlAuthenticator Arbitrary string to be used to authenticate the content URL (optional). This value is automatically embedded in the Content URL, if that url specifies the placeholder {s:authenticator}. No
logContentInfo if "true", logs contentURL, contentUrlAuthenticator, content ids, and a hash of the content keys. No
controlFlags MS3 Control Flags, as a 1-byte hex value. No
outputControlFlags MS3 Output Control Flags, as a 4-byte hex value. Must be provided if outputControlValue is specified. No
outputControlValue MS3 Output Control Value, as a 4-byte hex value. Must be provided if outputControlFlags is specified. No
ms3Extension A short form wrapping extensionType, extensionCriticalFlag, and extensionPayload, as a comma separated string. Either one of ms3Extension or extensionType/ extensionCriticalFlag/extensionPayload can be passed. See format below. Example: …&ms3Extension=wudo,false,AAAAAA==&… No, any number can be used
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, if used only one should be provided
extensionCriticalFlag "true" if critical, "false" if not critical. Yes, when extensionType is specified.
extensionPayload A base64 encoded string of the Extension description. Yes, when extensionType is specified.
ms3Scheme If "true", the url scheme of the token response will begin with ms3://. If "false" or parameter not specified, the url scheme will start with https:// No
cfid An 8 byte hexadecimal string reference to a manufacturer’s device super-encryption key used to encrypt the content key. This can be used only with device bound licenses. Only one content key can be specified. No
activeUserId A string representation of an active user id that is at most 64 characters long. No

5.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. 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. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. If the value is an integer preceded by a + sign, then it is interpreted as a relative number of seconds, from issuance, that the token is valid. For example, +60 specifies one minute. The maximum and default (if not specified) token lifetime is 30 days. Use the encoded form "%2B" when specifying the + sign. No
deviceId Device id to which to bind token. This value will be the same as the NEMO node id of the client device. No

Note about kid: For example, if the hash of string is: 0123456789ABCDEF0123456789ABCDEF01234567, the truncated SHA1 hash is 0123456789ABCDEF0123456789ABCDEF (first 32 characters)

Note: The contentURL parameter is treated as a template, with template parameters replaced with appropriate values. The only currently defined template parameter is s:authenticator, which will be replaced by the value of the authenticator parameter specified in the token generation request. A sample contentURL might be http://www.bok.net/music/get-token?auth= {s:authenticator}&cid=8967F56D

5.4   Correlation Parameters

Query Parameter Description Required?
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No

5.5   Example Queries

Production:
https://ms3-gen.{prod_domain}/hms/ms3/token?customerAuthenticator=790,0e8c78e70c574ddd82731f77b889c1b0&contentId.0=1234123412341234&contentKey.0=12311232123312341235123612371238&contentURL=www.test1234.com/test/test/test.mp4 https://ms3-gen.{prod_domain}/hms/ms3/token?customerAuthenticator=790,0e8c78e70c574ddd82731f77b889c1b0&contentId.0=1234123412341234&kek=01112233445566778899aabbccddeeff&kid.0=519139C2BD60DBE70F8C15714BF2A00B&contentURL=www.test1234.com/test/test/test.mp4
Test:
https://ms3-gen.test.expressplay.com/hms/ms3/token?customerAuthenticator=790,0e8c78e70c574ddd82731f77b889c1b0&contentId.0=1234123412341234&contentKey.0=12311232123312341235123612371238&contentURL=www.test1234.com/test/test/test.mp4 https://ms3-gen.test.expressplay.com/hms/ms3/token?customerAuthenticator=790,0e8c78e70c574ddd82731f77b889c1b0&contentId.0=1234123412341234&kek=01112233445566778899aabbccddeeff&kid.0=519139C2BD60DBE70F8C15714BF2A00BcontentURL=www.test1234.com/test/test/test.mp4

5.6   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error. text/uri-list MS3 Compound URI
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

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format. In the case of application/json, see JSON Errors for the representation of the error code and error message.

5.7   Event Error Codes

Code Description
-2001 Invalid token version
-2002 Invalid token expiration time: <details>
-2003 Invalid IP address
-2005 Invalid content key: <details>
-2006 Mismatch in number of content IDs and content keys specified
-2007 Invalid control flags specified: <details>
-2008 Invalid output control flags specified: <details>
-2009 Invalid output control value 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. IMPORTANT: 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
-2026 Missing content ID
-2027 Content key must be 32-hexadecimal digits long
-2029 Invalid content ID
-2030 ExpressPlay Admin error
-2031 Service Account Disabled
-2032 Invalid MS3 Token Type
-2033 Invalid cookie
-2035 No corresponding value specified
-2036 Extension type should be 4 characters
-2037 Extension payload should be Base64 encoded
-2038 Extension critical flag should be true or false
-2045 Only one of ms3Scheme or ms3SchemeType can be specified
-2046 Invalid ms3SchemeType value
-2048 Log content info flag should be true or false
-2054 Invalid cfid length specified
-2055 Invalid cfid specified
-2056 Invalid active user id length specified
-2057 Unauthorized service specified
-2058 Request parameters specified are unacceptable
-2059 Invalid MS3Extension parameters specified
-2060 Only one content key can be specified if cfid is provided
-2062 Marlin option disabled
-2149 Use either extensionType or ms3Extension parameter
-2150 Use only one parameter set with extensionType use ms3Extenstion parameter if several are required
-3004 Invalid error format specified: <format>
-3006 Content URL must be supplied
-4001 Device could not be authenticated
-4010 Invalid token
-4017 Mismatch in number of content IDs and kids specified
-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 ^
-4023 Mismatch in number of content IDs and encrypted keys specified
-4024 Invalid encrypted key or kek
-4025 Only one of ek or kid can be provided
-7001 At least one content ID must be supplied

6   Marlin Broadband Registration Token Request

Purpose
Requests a token that can be redeemed by customer to register a broadband device. Token is in the form of a Marlin action token.
URLs
Production:
https://bb-gen.{prod_domain}/hms/bb/token
Test:
https://bb-gen.test.expressplay.com/hms/bb/token
Method
GET, POST (with www-url-encoded body containing parameters for both the methods)

6.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes
actionTokenType Must be 0. Signifies registration action token. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

6.2   Registration Parameters

Query Parameter Description Required?
userId An id used to uniquely identify a user. This can be any value generated and managed by the requestor that uniquely identifies an end user. Yes
userKey The hexadecimal representation of a 16-byte seed value that ExpressPlay uses to generate a key to protect content keys in user-bound licenses. This value is should be generated, hard to guess, and permanently associated with the corresponding userId. Broadband license token requests for user-bound licenses will need to specify this same value (and userId). Yes
registrationEndTime Registration 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 string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the registration. 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 registration is issued that the registration will be valid. Use the encoded form "%2B" when specifying the + sign. No

6.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. 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 string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is an integer preceded by a + sign, then it is interpreted as a relative number of seconds, from issuance, that the token is valid. For example, +60 specifies one minute. The maximum and default (if not specified) token lifetime is 30 days. Use the encoded form "%2B" when specifying the + sign. No
deviceId Device id to which to bind token. This value will be the same as the NEMO node id of the client device. No

6.4   Correlation Parameters

Query Parameter Description Required?
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No

6.5   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error.
application/vnd.marlin.
drm.actiontoken+xml
Registration Action 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

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format. In the case of application/json, see JSON Errors for the representation of the error code and error message.

6.6   Event Error Codes

Code Description
-2001 Invalid token version
-2002 Invalid token expiration time: <details>
-2003 Invalid IP address
-2010 Invalid User Key: <details>
-2011 Missing user key
-2014 Missing action token type
-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. IMPORTANT: 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
-2030 ExpressPlay Admin error
-2031 Service Account Disabled
-2033 Invalid cookie
-2048 Log content info flag should be true or false
-3004 Invalid error format specified: <format>
-4001 Device could not be authenticated
-4016 Invalid registration end time

7   Marlin Broadband License Token Request

Purpose
Requests a token that can be redeemed by customer for a broadband license. Token is in the form of a Marlin action token.
URLs
Production:
https://bb-gen.{prod_domain}/hms/bb/token
Test:
https://bb-gen.test.expressplay.com/hms/bb/token
Method
GET, POST (with www-url-encoded body containing parameters for both the methods)

7.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes
actionTokenType Must be 1. Signifies license action token. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

7.2   License Parameters

Query Parameter Description Required?

contentId

contentId.N

URI that identifies the content id. Any number of these can be provided, but a matching number of contentKey parameters must be provided. If multiple contentId values are provided, they are correlated with corresponding contentKey values positionally. Alternatively, the parameters can be named contentId.0, contentId.1, etc. to match the corresponding contentKey.N parameters. Note that numbering is 0-based (the first content id must be contentId.0). Yes, unless kek and kid are provided.

contentKey

contentKey.N

A hexadecimal string representation of the content key associated with the corresponding contentId. Any number of these can be provided, but a matching number of contentId parameters must be provided. If contentKey parameter name is used to specify the content ids, then contentKey parameter name should be used for the content keys, and the order of content keys should match the content ids. If the content ids are specified using the contentId.N nomenclature, corresponding content keys must be named contentKey.0, contentKey.1, etc. to match the content ids. Note that numbering is 0-based (the first content key should be contentKey.0). Yes, unless kek and ek/kid are provided.
kek Key Encryption Key. Keys are stored encrypted with a KEK using a key wrapping algorithm (AES Key Wrap, RFC3394). If kek is supplied, either one of kid or ek needs to be supplied and not both. In both the cases, contentId needs to be provided. No

kid

kid.N

A unique 16 byte key id or a string ‘^somestring’. The length of the string followed by the ‘^’ cannot be greater than 64 characters. Any number of these can be provided. If a single kid is supplied, the parameter kid can be used. If multiple key ids are supplied, the parameters are to be named, kid.0, kid.1, etc. Note that the numbering is 0-based (the first key id should be kid.0). These have to match the number of content ids If kid is passed as a ‘^somestring’, kid is simply computed as the truncated SHA1 hash of the string. Check note below for an example. No

ek

ek.N

A hex string representation of the encrypted content key associated with the corresponding contentId. Any number of these can be provided but a matching number of contentId parameters must be provided. If a single encrypted content key is supplied, the parameter ek can be used. If multiple keys are supplied, the parameters should be named ek.0, ek.1, etc. to match the corresponding contentId.N parameters. Note that numbering is 0-based (the first encrypted content key should be ek.0). No
logContentInfo if "true", logs content ids, and a hash of content keys. No
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 license is issued that the license will be valid. The content cannot be played after this time. Only valid if rightsType is Rental. Rental date cannot exceed 5555-12-31T12:00:00Z Use the encoded form "%2B" when specifying the + sign. 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 and the license is bound to a user. No
userId An id used to uniquely identify a user. This can be any value generated and managed by the requestor that uniquely identifies an end user. It should match the value provided in the registration request for the same user. The hexadecimal representation of a 16-byte If not provided, the license will be bound to device. No
userKey The hexadecimal representation of a 16-byte seed value that ExpressPlay uses to generate a key to protect content keys in user-bound licenses. This value should match the value during the registration token request for the corresponding user. If userId is provided, then userKey must be supplied. If neither is supplied the license will be bound to the device. No
outputControlFlags A 4-byte hex value to indicate which values from the outputControlValue will be used. See outputControlFlags section below for details. No
outputControlValue A 4-byte hex value used to store values of the desired OutputControl in the license. See outputControlValue section below for details. Yes, if outputControlFlags is specified
outputControlObligation

A comma separated list of 3 strings indicating the technology ID, the parameter name, and the parameter value. Any number can be provided. When the technology is SecureContentPath and the parameter name is SecurityClass, the value is a . separated list of 3 strings: – base64 encoded content ID ASCII encoding is used for contentId prior to base64 encoding – an int representing the "portions" – base64 encoded predicate byte array See the OutputControl Specification 1.0.3+ Examples: outputControlObligation=SecureContentPath, DefaultSecurityClass,0

outputControlObligation=SecureContentPath,
SecurityClass,<base64 contentid>
.<int portion>.<base64 predicate>
No
outputControlOverride A comma separated list of 3 strings indicating the technology ID, the parameter name, and the parameter value. Any number can be provided. See above for SecureContentPath handling. No
outputControlOverrideId deprecated use outputControlObligation Unique identifier for output control technology. A string id, for example "urn:marlin:organization:intertrust:wudo". Must not contain ‘ ‘, ‘\’, ”, ‘&’, ‘<‘, ‘>’, ‘[‘, ‘]’, ‘^’, ‘`’, ‘{‘, ‘|’, ‘}’, ‘~’. No
outputControlOverrideParameter deprecated use outputControlObligation A string parameter name, for example "ImageConstraintLevel". Valid if outputControlOverrideId is specified. Must not contain ‘ ‘, ‘\’, ”, ‘&’, ‘<‘, ‘>’, ‘[‘, ‘]’, ‘^’, ‘`’, ‘{‘, ‘|’, ‘}’, ‘~’. Yes, if outputControlOverrideId is present
outputControlOverrideValue deprecated use outputControlObligation An integer value. for example 0. Valid if outputControlOverrideParameter is specified. Yes, if outputControlOverrideParameter is present
cfid An 8 byte hexadecimal string reference to a manufacturer’s device super-encryption key used to encrypt the content key. This can be used only with device bound licenses. Only one content key can be specified. No
activeUserId A string representation of an active user id that is at most 64 characters long. No

7.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST a string in RFC 3339 date/time format in the ‘Z’ zone designator ("Zulu time") or an integer preceded by a + sign. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. If the value is an integer preceded by a + sign, then it is interpreted as a relative number of seconds, from issuance, that the token is valid. For example, +60 specifies one minute. The maximum and default (if not specified) token lifetime is 30 days. Use the encoded form "%2B" when specifying the + sign. No
deviceId Device id to which to bind token. This value will be the same as the NEMO node id of the client device. No

7.4   Correlation Parameters

Query Parameter Description Required?
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No

7.5   outputControlFlags:

bit vector of flags indicating which fields are signalled in the outputControlValue. When a flag in this vector is set to 1, the Client SHALL set the output control parameters as specified by the corresponding bit-field in the outputControlValue.
Flag Bit (0 is the least significant bit) Output Control Technology Field name
0 BasicCCI DigitalOnlyToken
1 BasicCCI EPN
2 BasicCCI CCI
3 BasicCCI ImageConstraintToken
4 BasicCCI APS
5 DTCP RetentionMoveMode
6 DTCP RetentionState
7 DTCP EPN
8 DTCP DTCP_CCI
9 DTCP ImageConstraintToken
10 DTCP APS

7.6   outputControlValue:

bit fields indicating the value of zero or more output control fields.The fields are encoded as follows:
Bit range (0 is the least significant bit) Output Control Technology Field name
0 BasicCCI DigitalOnlyToken
1.4 BasicCCI Reserved
5 BasicCCI EPN
6.7 BasicCCI CCI
8 BasicCCI ImageConstraintToken
9.10 BasicCCI APS
11 DTCP RetentionMoveMode
12..14 DTCP RetentionState
15 DTCP EPN
16..17 DTCP DTCP_CCI
18 DTCP ImageConstraintToken
19..20 DTCP APS

7.7   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error.
application/vnd.marlin.
drm.actiontoken+xml
License Action 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

Note about kid: For example, if the hash of string is: 0123456789ABCDEF0123456789ABCDEF01234567, the truncated SHA1 hash is 0123456789ABCDEF0123456789ABCDEF (first 32 characters)

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format.Error codes will be negative integer values. Currently defined error codes are:

7.8   Event Error Codes

Code Description
-2001 Invalid token version
-2002 Invalid token expiration time: <details>
-2003 Invalid IP address
-2005 Invalid content key: <details>
-2006 Mismatch in number of content IDs and content keys specified
-2008 Invalid output control flags specified: <details>
-2009 Invalid output control value specified: <details>
-2010 Invalid user key: <details>
-2011 Missing user key
-2013 Invalid action token type: <details>
-2014 Missing action token type
-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. IMPORTANT: 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
-2026 Missing content ID
-2027 Content key must be 32-hexadecimal digits long
-2029 Invalid content ID
-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
-2039 OutputControlFlags and OutputControlValue are inconsistent
-2040 OutputControlFlag must be encode 4 bytes
-2041 OutputControlValue must encode 4 bytes
-2042 Invalid outputControlOverrideId
-2043 Invalid outputControlOverrideParameter
-2048 Log content info flag should be true or false
-2054 Invalid cfid length specified
-2055 Invalid cfid specified
-2056 Invalid active user id length specified
-2060 Only one content key can be specified if cfid is provided
-2145 OutputControl Params are of the form technology,param,value
-2146 Invalid SecurityClass parameter format
-2147 Use either outputControlFlags or outputControlObligation for specifying output control technologies
-2148 Invalid output control parameter for this technology
-2151 Use either outputControlOverrideId or outputControlOverride for specifying output control override technologies
-3004 Invalid error format specified: <format>
-3006 Content URL must be supplied
-4001 Device could not be authenticated
-4017 Mismatch in number of content IDs and kids specified
-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 ^
-4023 Mismatch in number of content IDs and encrypted keys specified
-4024 Invalid encrypted key or kek
-4025 Only one of ek or kid can be provided
-7001 At least one content ID must be supplied

8   Marlin Broadband Deregistration Token Request

Purpose
Requests a token that can be redeemed by customer to deregister a broadband device. Token is in the form of a Marlin action token.
URLs
Production:
https://bb-gen.{prod_domain}/hms/bb/token
Test:
https://bb-gen.test.expressplay.com/hms/bb/token
Method
GET, POST (with www-url-encoded body containing parameters for both the methods)

8.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes
actionTokenType Must be 2. Signifies deregister action token. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

8.2   Deregistration Parameters

Query Parameter Description Required?
userId An id used to uniquely identify a user. This can be any value generated and managed by the requestor that uniquely identifies an end user. "userId" must be the same value as the "userId" in the corresponding "register" action token request. Yes

8.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST a string in RFC 3339 date/time format in the ‘Z’ zone designator ("Zulu time") or an integer preceded by a + sign. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is an integer preceded by a + sign,then it is interpreted as a relative number of seconds, from issuance, that the token is valid.For example,+60 specifies one minute. The maximum and default(if not specified) token lifetime is 30 days. Use the encoded form "%2B" when specifying the + sign. No
deviceId Device id to which to bind token. This value will be the same as the NEMO node id of the client device. No

8.4   Correlation Parameters

Query Parameter Description Required?
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No

8.5   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error. application/vnd.marlin.drm.act iontoken+xml Deregistration Action 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

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format. In the case of application/json, see JSON Errors for the representation of the error code and error message.

8.6   Event Error Codes

Code Description
-2001 Invalid token version
-2002 Invalid token expiration time: <details>
-2013 Invalid action token type: <details>
-2014 Missing action token type
-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. IMPORTANT: 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
-2030 ExpressPlay Admin error
-2031 Service Account Disabled
-2033 Invalid cookie
-2048 Log content info flag should be true or false
-3004 Invalid error format specified: <format>
-4001 Device could not be authenticated

9   PlayReady License Token Request

Purpose
Requests a token that can be redeemed by customer for a PlayReady license.
URLs
Production:
https://pr-gen.{prod_domain}/hms/pr/token
Test:
https://pr-gen.test.expressplay.com/hms/pr/token
Method
GET, POST (with www-url-encoded body containing parameters for both the methods)

9.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

9.2   License Parameters

Query Parameter Description Required?
generalFlags A 4 byte hexadecimal string representing the license flags. When set to ‘00000000’ the license will be non-persistent, eg a new license will be required for each playback such as is usual in streaming scenarios. Rental licenses (rightsType=Rental) and Buy-To-Own license SHOULD be flagged with ‘00000001′ to persist at the client, and to allow content to be played repeatedly without requiring a new license each time. No
kek Key Encryption Key. Keys are stored encrypted with a KEK using a key wrapping algorithm (AES Key Wrap, RFC3394). No

kid

kid.N

A 16 byte hexadecimal string representation of the content encryption key id or a string ‘^somestring’. The length of the string followed by the ‘^’ cannot be greater than 64 characters. Any number of these can be provided. If a single kid is supplied, the parameter kid can be used. If multiple key ids are supplied, the parameters are to be named, kid.0, kid.1, etc. Note that the numbering is 0-based (the first key id should be kid.0). These have to match the number of content keys. If kid is passed as a ‘^somestring’, kid is simply computed as the truncated SHA1 hash of the string. Check note below for an example. Yes

ek

ek.N

A hex string representation of the encrypted content key associated with the corresponding key id. Any number of these can be but a matching number of kid parameters must be provided. If a single encrypted content key is supplied, the parameter ek can be used. If multiple keys are supplied, the parameters should be named ek.0, ek.1, etc. to match the corresponding kid.N parameters. Note that numbering is 0-based (the first encrypted content key should be ek.0). No

contentKey

contentKey.N

A 16 byte hexadecimal string representation of the content encryption key. Any number of these can be provided, but a matching number of kid parameters must be provided. If a single contentKey is supplied, the parameter contentKey can be used. If multiple keys are supplied, the parameters should be named contentKey.0, contentKey.1, etc. to match the corresponding kid.N parameters. Note that numbering is 0-based (the first content key should be contentKey.0). Yes, unless kek and ek/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. Use the encoded form "%2B" when specifying the + sign. 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.
minCertSecurityLevel Security level (0-3000) No
useHttps If a value of "true" is passed, license service url will contain https in the response. No

9.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST a string in RFC 3339 date/time format in the ‘Z’ zone designator ("Zulu time") or an integer preceded by a + sign. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. If the value is an integer preceded by a + sign, then it is interpreted as a relative number of seconds, from issuance, that the token is valid. For example, +60 specifies one minute. The maximum and default (if not specified) token lifetime is 30 days. Use the encoded form "%2B" when specifying the + sign. No
deviceId A 16 byte hexadecimal string to represent the Device id to which to bind token. No

9.4   Correlation Parameters

Query Parameter Description Required?
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No

9.5   HTTP Response

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

The response of the ExpressPlay REST API for PlayReady License Token Request is a JSON payload that contains two fields: “licenseAcquisitionUrl" and “token". Refer to the following link for more details:

http://www.expressplay.com/developer/playready-apps

Note about kid: For example, if the hash of string is: 0123456789ABCDEF0123456789ABCDEF01234567, the truncated SHA1 hash is 0123456789ABCDEF0123456789ABCDEF (first 32 characters)

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format.Error codes will be negative integer values. Currently defined error codes are:

9.6   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. IMPORTANT: 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
-5008 Invalid cookie length

10   FairPlay License Token Request

Purpose
Requests a token that can be redeemed by customer for a FairPlay license.
URLs
Production:
https://fp-gen.{prod_domain}/hms/fp/token
Test:
https://fp-gen.test.expressplay.com/hms/fp/token
Method
GET, POST (with www-url-encoded body containing parameters for both the methods)

10.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

10.2   License Parameters

Query Parameter Description Required?
generalFlags A 4 byte hexadecimal string representing the license flags. Allowed values are as follows: ‘00000000’ – (default value) no persistence ‘00000001’ – persistent license No
kek Key Encryption Key. Keys are stored encrypted with a KEK using a key wrapping algorithm (AES Key Wrap, RFC3394). If kek is supplied, either one of kid or ek needs to be supplied and not both. No
kid A 16 byte hexadecimal string representation of the content encryption key id or a string ^somestring’. The length of the string followed by the ‘^’ cannot be greater than 64 characters. Check note below for an example. No
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/kid are provided
iv A 16 byte hexadecimal string representation of the content encryption IV Yes
rentalDuration Duration of the rental in seconds (default – 0) No
fpExtension A short form wrapping extensionType and extensionPayload, as a comma separated string. See format below. Example: …&fpExtension=wudo,AAAAAA==&… No, any number can be used
useHttps If a value of "true" is passed, license service url will contain https in the response. No

10.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST a string in RFC 3339 date/time format in the ‘Z’ zone designator ("Zulu time") or an integer preceded by a + sign. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. If the value is an integer preceded by a + sign, then it is interpreted as a relative number of seconds, from issuance, that the token is valid. For example, +60 specifies one minute. The maximum and default (if not specified) token lifetime is 30 days. Use the encoded form "%2B" when specifying the + sign. No
deviceId A 16 byte hexadecimal string to represent the Device id to which to bind token. No

10.4   Correlation Parameters

Query Parameter Description Required?
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No

10.5   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error. text/uri-list License acquisition url + 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

The response of the ExpressPlay REST API for FairPlay License Token Request is of type text/uri-list containing the license acquisition url + license token as a ExpressPlayToken query parameter.

For example:

https://fp-gen.{prod_domain}/hms/fp/rights/?ExpressPlayToken=AQAAAJJ2Y0MAAABQbyvnJ6KgEg_w-2yZmU-MsjTEZ3f7UkhUcFhDFAvdonzBkRGQU-xe1G-DMbel5-BVH_PozovdWhKZx0_SXRokfh9-FERmBl6OEfGfPqMI1eO1PqRkx59Q2q1s2cFNrqfml8Y3RQ

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format.Error codes will be negative integer values. Currently defined error codes are:

10.6   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. IMPORTANT: 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
-2053 Invalid content type specified
-3004 Invalid error format specified: <format>
-4001 Device could not be authenticated
-4010 Invalid token
-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
-5003 Invalid general flags
-6001 Invalid FPExtension parameters specified
-6002 Invalid FP Token Type
-6003 Invalid IV parameter specified
-6004 Failed to generate CKC for FP
-6005 Invalid key data specified
-6006 Service not authorized for FairPlay support
-6007 Invalid rental duration specified
-6009 FairPlay option disabled

11   Widevine License Token Request

Purpose
Requests a token that can be redeemed by customer for a Widevine license.
URLs
Production:
https://wv-gen.{prod_domain}/hms/wv/token
Test:
https://wv-gen.test.expressplay.com/hms/wv/token
Method
GET, POST (with www-url-encoded body containing parameters for both the methods)

11.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

11.2   License Parameters

Query Parameter Description Required?
generalFlags A 4 byte hexadecimal string representing the license flags. Allowed values are as follows: ‘00000000’ – (default value) no persistence ‘00000001’ – persistent license No
kek Key Encryption Key. Keys are stored encrypted with a KEK using a key wrapping algorithm (AES Key Wrap, RFC3394). No

kid

kid.N

A 16 byte hexadecimal string representation of the content encryption key id or a string ‘^somestring’. The length of the string followed by the ‘^’ cannot be greater than 64 characters. Any number of these can be provided. If a single kid is supplied, the parameter kid can be used. If multiple key ids are supplied, the parameters are to be named, kid.0, kid.1, etc. Note that the numbering is 0-based (the first key id should be kid.0). These have to match the number of content keys If kid is passed as a ‘^somestring’, kid is simply computed as the truncated SHA1 hash of the string. Check note below for an example. Yes

ek

ek.N

A hex string representation of the encrypted content key associated with the corresponding key id. Any number of these can be but a matching number of kid parameters must be provided. If a single encrypted content key is supplied, the parameter ek can be used. If multiple keys are supplied, the parameters should be named ek.0, ek.1, etc. to match the corresponding kid.N parameters. Note that numbering is 0-based (the first encrypted content key should be ek.0). No

contentKey

contentKey.N

A 16 byte hexadecimal string representation of the content encryption key. Any number of these can be provided, but a matching number of kid parameters must be provided. If a single contentKey is supplied, the parameter contentKey can be used. If multiple keys are supplied, the parameters should be named contentKey.0, contentKey.1, etc. to match the corresponding kid.N parameters. Note that numbering is 0-based (the first content key should be contentKey.0). Yes, unless kek and ek/kid are provided.
contentId Content Id. Max length is 36 bytes. No

trackType

trackType.N

Allowed values are 0-4. (Default = 1) 0 = SD, 1 = HD, 2 = AUDIO, 3 = UHD1, 4 = UHD2 Any number of these can be provided, but a matching number of kid parameters must be provided. If a single trackType is supplied, the parameter trackType can be used. If multiple keys are supplied, the parameters should be named trackType.0, trackType.1, etc. to match the corresponding kid.N parameters. Note that numbering is 0-based (the first track type should be trackType.0). No

securityLevel

securityLevel.N

Allowed values are 1-5. (Default = 1) 1 = SW_SECURE_CRYPTO, 2 = SW_SECURE_DECODE 3 = HW_SECURE_CRYPTO, 4 = HW_SECURE_DECODE 5 = HW_SECURE_ALL Any number of these can be provided, but a matching number of kid parameters must be provided. If a single securityLevel is supplied, the parameter securityLevel can be used. If multiple keys are supplied, the parameters should be named securityLevel.0, securityLevel.1, etc. to match the corresponding kid.N parameters. Note that numbering is 0-based (the first security level should be securityLevel.0). No

hdcpOutputControl

hdcpOutputControl.N

Allowed values are 0-5. (Default = 0) 0 = HDCP_NONE, 1 = HDCP_V1, 2 = HDCP_V2 3 = HDCP_V2_1, 4 = HDCP_V2_2 5 = HDCP_NO_DIGITAL_OUTPUT Any number of these can be provided, but a matching number of kid parameters must be provided. If a single hdcpOutputControl is supplied, the parameter hdcpOutputControl can be used. If multiple keys are supplied, the parameters should be named hdcpOutputControl.0, hdcpOutputControl.1, etc. to match the corresponding kid.N parameters. Note that numbering 0-based (the first hdcpOutputControl should be hdcpOutputControl.0). No

cgmsFlagsOutputControl

cgmsFlagsOutputControl.N

Allowed values are 0, 1, 2, 3. (Default = 0) 0 = CGMS_NONE, 1 = CGMS_FREE, 2 = CGMS_ONCE, 3 = CGMS_NEVER Any number of these can be provided, but a matching number of kid parameters must be provided. If a single cgmsFlagsOutputControl is supplied, the parameter cgmsFlagsOutputControl can be used. If multiple keys are supplied, the parameters should be named cgmsFlagsOutputControl.0, cgmsFlagsOutputControl.1, etc. to match the corresponding kid.N parameters. Note that numbering 0-based (the first cgmsFlagsOutputControl should be cgmsFlagsOutputControl.0). No

disableAnalogOutput

disableAnalogOutput.N

Allowed values are 0, 1. (Default = 0) Indicates whether analog output is allowed. 0 = DISABLE_ANALOG_OUTPUT_FALSE, 1 = DISABLE_ANALOG_OUTPUT_TRUE Any number of these can be provided, but a matching number of kid parameters must be provided. If a single disableAnalogOutput is supplied, the parameter disableAnalogOutput can be used. If multiple keys are supplied, the parameters should be named disableAnalogOutput.0, disableAnalogOutput.1, etc. to match the corresponding kid.N parameters. Note that numbering 0-based (the first disableAnalogOutput should be disableAnalogOutput.0). No

hdcpSrmRule

hdcpSrmRule.N

Allowed values are 0, 1. (Default = 0) Use CURRENT_SRM to not allow this key if the device has an older SRM and cannot support SRM updates. 0 = HDCP_SRM_RULE_NONE, 1 = CURRENT_SRM Any number of these can be provided, but a matching number of kid parameters must be provided. If a single hdcpSrmRule is supplied, the parameter hdcpSrmRule can be used. If multiple keys are supplied, the parameters should be named hdcpSrmRule.0, hdcpSrmRule.1, etc. to match the corresponding kid.N parameters. Note that numbering 0-based (the first hdcpSrmRule should be hdcpSrmRule.0). No
licenseDuration Duration of the license in seconds. If not provided, it indicates that there is no limit to the duration. Please check note below for detailed information. No
playbackDuration The viewing window of time once playback starts within the license duration. If not provided, it indicates that there is no limit to the duration. No
allowUnverifiedPlatform A license request will fail if VMP status is unverified or tampered for a desktop browser. Set this field to ‘true’ to allow license request to succeed when VMP status is unverified. No
wvExtension A short form wrapping extensionType and extensionPayload, as a comma separated string. See format below. Example: …&wvExtension=wudo,AAAAAA==&… No, any number can be used

Note about licenseDuration:

  1. Playback will stop licenseDuration seconds after beginning of playback.
  2. To allow playback to be stopped/resumed for an unlimited amount of time, omit licenseDuration (it will default to infinite). Otherwise specify the amount of time during which end-users should be able to enjoy the stream

Note about VMP:

Verified Media Path (VMP) The Verified Media Path (VMP) feature is implemented for desktop browser platforms. It describes Widevine’s method to authenticate the browser software stack that is interfacing with the Widevine CDM.

11.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST a string in RFC 3339 date/time format in the ‘Z’ zone designator ("Zulu time") or an integer preceded by a + sign. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. If the value is an integer preceded by a + sign, then it is interpreted as a relative number of seconds, from issuance, that the token is valid. For example, +60 specifies one minute. The maximum and default (if not specified) token lifetime is 30 days. Use the encoded form "%2B" when specifying the + sign. No
deviceId A 16 byte hexadecimal string to represent the Device id to which to bind token. No

11.4   Correlation Parameters

Query Parameter Description Required?
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No

11.5   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error. text/uri-list License acquisition url + 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

The response of the ExpressPlay REST API for Widevine License Token Request is of type text/uri-list containing the license acquisition url + license token as a ExpressPlayToken query parameter.

For example:

https://wv-gen.{prod_domain}/hms/wv/rights/?ExpressPlayToken=AQAAAJJ2Y0MAAABQbyvnJ6KgEg_w-2yZmU-MsjTEZ3f7UkhUcFhDFAvdonzBkRGQU-xe1G-DMbel5-BVH_PozovdWhKZx0_SXRokfh9-FERmBl6OEfGfPqMI1eO1PqRkx59Q2q1s2cFNrqfml8Y3RQ

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format.Error codes will be negative integer values. Currently defined error codes are:

11.6   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. IMPORTANT: 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
-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
-4010 Invalid token
-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
-5003 Invalid general flags
-6005 Invalid key data specified
-6007 Invalid rental duration specified
-7003 Missing security level value
-7004 Invalid security level value
-7006 Missing HDCP output control value
-7007 Invalid license duration specified
-7008 Failed to generate Widevine license
-7009 Invalid WVExtension parameters specified
-7011 Widevine option disabled
-7012 Widevine device id mismatch
-7013 Invalid playback duration specified
-7014 Invalid CGMS flags output control specified
-7015 Mismatch in number of kids and content keys specified
-7018 Mismatch in number of track types specified
-7019 Invalid track type specified
-7020 Mismatch in number of security levels specified
-7021 Invalid track type specified
-7022 Mismatch in number of cgms flags output control specified
-7023 Invalid content id length specified
-7024 Mismatch in number of content key specified
-7025 Invalid disable analog output specified
-7026 Invalid hdcp srm rule specified
-7027 Mismatch in number of disable analog outputs specified
-7028 Mismatch in number of hdcp srm rules specified

12   Primetime License Token Request

Purpose
Requests a token that can be redeemed by customer for an Adobe Primetime license.
URLs
Production:
https://pt-gen.{prod_domain}/hms/pt/token
Method
GET, POST (with www-url-encoded body containing parameters for both the methods)

12.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

12.2   License Parameters

Query Parameter Description Required?
generalFlags A 4 byte hexadecimal string representing the license flags. Allowed values are as follows: ‘00000000’ – (default value) no persistence or iOS key server. ‘00000001’ – persistent license ‘00000002’ – use the iOS key server ‘00000003’ – used to indicate both No
kek Key Encryption Key. 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 id or a string ^somestring’. The length of the string followed by the ‘^’ cannot be greater than 64 characters. Check note below for an example. No
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/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 license is issued that the license will be valid. The content cannot be played after this time. Only valid if rightsType is Rental. Rental date cannot exceed 5555-12-31T12:00:00Z Use the encoded form "%2B" when specifying the + sign. 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
securityFlags Flags that govern certain security features that are required. Allowed value is 1. 1 –> ENFORCE_JAILBREAK, if set, for devices that support jailbreak detection, do not allow playback if received. No
drmLevel Default is 0. Refer to the Adobe manual No
runtimeLevel Default is 0. Refer to the Adobe manual No
analogOutputProtection Analog output protection. Allowed values are: NO_PROTECTION = 0, USE_IF_AVAILABLE = 1, USE_IF_AVAILABLE_ACP = 2, USE_IF_AVAILABLE_CGMSA = 3, REQUIRED = 4, REQUIRED_ACP = 5, REQUIRED_CGMSA = 6, NO_PLAYBACK = 7 No
digitalOutputProtection Digital output protection. Allowed values are: NO_PROTECTION = 0, USE_IF_AVAILABLE = 1, REQUIRED = 2, NO_PLAYBACK = 3 No
rbopParameter Base64 encoded JSON string containing the resolution based output protection values No
ptExtension A short form wrapping extensionType and extensionPayload, as a comma separated string. See format below. Example: …&ptExtension=apol,AAAAAA==&… Extension type: ‘apol’ with payload of pre-generated Primetime policy. This takes precedence over the other fields, so when this extension is used, the other fields of the token that relate to policies are ignored. No, any number can be used

12.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST a string in RFC 3339 date/time format in the ‘Z’ zone designator ("Zulu time") or an integer preceded by a + sign. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. If the value is an integer preceded by a + sign, then it is interpreted as a relative number of seconds, from issuance, that the token is valid. For example, +60 specifies one minute. The maximum and default (if not specified) token lifetime is 30 days. Use the encoded form "%2B" when specifying the + sign. No
deviceId A string to represent the device id to which to bind token. No

12.4   Correlation Parameters

Query Parameter Description Required?
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No

12.5   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error. text/uri-list License acquisition url + 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

The response of the ExpressPlay REST API for Widevine License Token Request is of type text/uri-list containing the license acquisition url + license token as a ExpressPlayToken query parameter.

For example:

https://pt-gen.{prod_domain}/hms/pt/rights/?ExpressPlayToken=AQAAAJJ2Y0MAAABQbyvnJ6KgEg_w-2yZmU-MsjTEZ3f7UkhUcFhDFAvdonzBkRGQU-xe1G-DMbel5-BVH_PozovdWhKZx0_SXRokfh9-FERmBl6OEfGfPqMI1eO1PqRkx59Q2q1s2cFNrqfml8Y3RQ

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format.Error codes will be negative integer values. Currently defined error codes are:

12.6   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. IMPORTANT: 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
-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
-4010 Invalid token
-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
-5003 Invalid general flags
-6005 Invalid key data specified
-6007 Invalid rental duration specified
-9201 Invalid PTExtension parameters specified
-9202 Invalid security flags specified
-9203 Invalid analog output protection specified
-9204 Invalid digital output protection specified
-9206 Primetime option disabled
-9207 Failed to parse resolution based output protection json string
-9208 Failed to generate PT license
-9209 Primetime device id mismatch

13   TLS License Token Request

Purpose
Requests a token that can be redeemed by customer for a TLS license.
URLs
Production:
https://tls-gen.{prod_domain}/hms/tls/token
Method
GET, POST (with www-url-encoded body containing parameters for both the methods)

13.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

13.2   License Parameters

Query Parameter Description Required?
generalFlags A 4 byte hexadecimal string representing the license flags. ‘0000’ is the only allowed value No
kek Key Encryption Key. 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 id or a string ^somestring’. The length of the string followed by the ‘^’ cannot be greater than 64 characters. Check note below for an example. No
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/kid are provided
responseKeyFormat Format of the key in the response. Default is 0. If set to 0, bytes returned in the response are an exact copy of the contentKey field. 0 is the only allowed value. No
tlsExtension A short form wrapping extensionType and extensionPayload, as a comma separated string. See format below. Example: …&tlsExtension=wudo,AAAAAA==&… No, any number can be used

13.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST a string in RFC 3339 date/time format in the ‘Z’ zone designator ("Zulu time") or an integer preceded by a + sign. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. If the value is an integer preceded by a + sign, then it is interpreted as a relative number of seconds, from issuance, that the token is valid. For example, +60 specifies one minute. The maximum and default (if not specified) token lifetime is 30 days. Use the encoded form "%2B" when specifying the + sign. No
deviceId A 16 byte hexadecimal string to represent the Device id to which to bind token. No

13.4   Correlation Parameters

Query Parameter Description Required?
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No

13.5   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error. text/uri-list License acquisition url + 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

The response of the ExpressPlay REST API for TLS License Token Request is of type text/uri-list containing the license acquisition url + license token as a ExpressPlayToken query parameter.

For example:

https://tls-gen.{prod_domain}/hms/tls/rights/?ExpressPlayToken=AQAAAJJ2Y0MAAABQbyvnJ6KgEg_w-2yZmU-MsjTEZ3f7UkhUcFhDFAvdonzBkRGQU-xe1G-DMbel5-BVH_PozovdWhKZx0_SXRokfh9-FERmBl6OEfGfPqMI1eO1PqRkx59Q2q1s2cFNrqfml8Y3RQ

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format.Error codes will be negative integer values. Currently defined error codes are:

13.6   Note about the "^somestring" for Kid for all the DRMs:

https://wv-gen.{prod_domain}.expressplay.com/hms/wv/token?customerAuthenticator=<your customer authenticator>&errorFormat=json&contentId=somecontentid&kid=^anykidstring&hdcpOutputControl=0&securityLevel=1&rentalDuration=%2B36000&playbackDuration=%2B23654656&kek=01112233445566778899aabbccddeeff

13.7   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. IMPORTANT: 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
-2027 Content encryption key must be 32-hexadecimal digits long
-2030 ExpressPlay Admin error: <details>
-2031 Service Account Disabled
-2033 Invalid cookie
-2036 Extension type should be 4 characters
-2037 Extension payload should be Base64 encoded
-3004 Invalid error format specified: <format>
-4001 Device could not be authenticated
-4010 Invalid token
-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
-5003 Invalid general flags
-6005 Invalid key data specified
-9500 Invalid TLS response key format specified
-9501 Invalid TLSExtension parameters specified
-9502 Failed to generate TLS license
-9503 TLS option disabled

14   Universal License Token Request

Purpose

Requests a token that can be redeemed by a customer for a Marlin (BB, MS3), Fairplay, Widevine or a Playready license.

To redeem a token for a Widevine license, the following header must be set, otherwise the server will not issue a correct license. Request header during token redemption: "utoken-drm : wv".

URLs
Production:
https://ut-gen.{prod_domain}/hms/ut/token
Test:
https://ut-gen.test.expressplay.com/hms/ut/token
Method
POST (with a json body containing parameters for all the DRMs)

14.1   An example of JSON request payload for UT:

{
   "expirationTime": "2017-10-20T12:01:10Z",
   "generalFlags": "00000000",
   "kek": "",
   "ek": [],
   "kids": ["b366360da82e9c6e0b0984002a362c00"],
   "contentKeys": ["a0a1a2a3a4a5a6a7a8a9aaabacadae00"],
   "contentIds": ["urn:marlin:kid:b366360da82e9c6e0b0984002a362c00"],
   "cookie": "",
   "marlinbb": {
       "bbActionTokenType": "1",
       "bbDeviceId": "",
       "bbRightsType": "BuyToOwn",
       "bbOutputControlFlags": "",
       "bbOutputControlValue": "",
       "bbOutputControlObligation": ["SecureContentPath,SecurityClass,dXJuOm15b3RoZXJjb250ZW50aWQ=.1.AAAAAAg=="],
       "bbOutputControlOverride": ["SecureContentPath,SecurityClass,dXJuOm15b3RoZXJjb250ZW50aWQ=.1.AAAAAAg=="],
       "bbRentalPeriodEndTime": ""
   },
   "marlinms3": {
       "ms3ControlFlags" : "00",
       "ms3DeviceId": "",
       "ms3OutputControlFlags": "00000000",
       "ms3OutputControlValue" : "00000000",
       "ms3ExtensionData": ["wudo,false,AAAAAA=="]
   },
   "fp": {
       "fpDeviceId": "",
       "fpRentalDuration":
        3600,
        "fpIv": "000102030405060708090a0b0c0d0e0f",
       "fpExtensionData": ["ext1,23jdfdnfd", "ext2,23jdfdnfd"]
   },
   "pr": {
       "prDeviceId": "",
       "prMinCertSecurityLevel": 2000,
       "prRightsType": "Rental",
       "prRentalPeriodEnd": "+3600",
       "prRentalPlayDuration": 3600,
       "prAnalogVideoOPL": 100,
       "prCompressedDigitalAudioOPL": 100,
       "prCompressedDigitalVideoOPL": 100,
       "prUncompressedDigitalAudioOPL": 100,
       "prUncompressedDigitalVideoOPL": 100,
       "prUnknownOutputBehavior": "Allow",
       "prExtensionData": ["pex1,payload1","pex2,payload2"],
       "prOutputControlFlags": "00000000",
       "prAppRestriction": ""
  },
  "wv": {
       "wvContentId": "",
       "wvDeviceId": "",
       "wvTrackTypes": [1],
       "wvSecurityLevels": [1],
       "wvHdcpOutputControls": [1],
       "wvCgmsFlagsOutputControls": [1],
       "wvDisableAnalogOutputs": [0],
       "wvHdcpSrmRules": [0],
       "wvLicenseDuration": 36000,
       "wvPlaybackDuration": 23654656,
       "wvExtensionData": ["ext1,23jdfdnfd","ext2,23jdfdnfd"]
  }
}

14.2   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. 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 will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

14.3   License Parameters passed in the JSON file:

Common parameters:
 
Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST a string in RFC 3339 date/time format in the ‘Z’ zone designator ("Zulu time") or an integer preceded by a + sign. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. If the value is an integer preceded by a + sign, then it is interpreted as a relative number of seconds, from issuance, that the token is valid. For example, +60 specifies one minute. The maximum and default (if not specified) token lifetime is 30 days. No
generalFlags A 4 byte hexadecimal string representing the license flags. Allowed values are as follows: ‘00000000’ – (default value) no persistence ‘00000001’ – persistent license No
kek Key Encryption Key. Keys are stored encrypted with a KEK using a key wrapping algorithm (AES Key Wrap, RFC3394). No
kids An array 16 byte hexadecimal string representation of the content encryption key id or a string ‘^somestring’. The length of the string followed by the ‘^’ cannot be greater than 64 characters. Any number of these can be provided. The parameters are to be provided as an array. These have to match the number of content keys and content ids. If kid is passed as a ‘^somestring’, kid is simply computed as the truncated SHA1 hash of the string after the ‘^’. If multiple kids are provided and if the token is used to acquire a Fairplay license, the first kid in the list will be used and must correspond to a video track. Yes
ek A hex string representation of the encrypted content key associated with the corresponding key id. Any number of these can be provided. The parameters are to be provided as an array. These have to match the number of kids. If multiple ek’s are provided and if the token is used to acquire a Fairplay license, the first ek in the list will be used and must correspond to a video track. No
contentIds URI that identifies a content id. Any number of these can be provided, but a matching number of kids and contentKey parameters must be provided. The parameters are to be provided as an array. If contentIds are not provided and if ‘kek’ and ‘kids’ are present, they are computed as "urn:marlin:kid:<KID>" where KID is the kid provided as an input. If kid is passed as a ‘^somestring’, kid is simply computed as the truncated SHA1 hash of the string after the ‘^’. No
contentKeys A 16 byte hexadecimal string representation of the content encryption key. Any number of these can be provided, but a matching number of kids and contentIds parameters must be provided. The parameters are to be provided as an array. If multiple contentKeys are provided and if the token is used to acquire a Fairplay license, the first contentKey in the list will be used and must correspond to a video track. Yes, unless kek and ek/kid are provided.
cookie Arbitrary string up to 32 characters long carried in the token and logged by the token redemption server. Can be used to correlate log entries at the redemption server and those at the service provider’s servers. No
marlinbb:
Query Parameter Description Required?
bbActionTokenType Must be 1. Signifies license action token. No
bbDeviceId A string to represent the Device id to which to bind token. No
bbRightsType Specifies the kind of rights. Must be BuyToOwn or Rental. No
bbOutputControlFlags A 4-byte hex value to indicate which values from the outputControlValue will be used. See outputControlFlags section for details. No
bbOutputControlValue A 4-byte hex value used to store values of the desired OutputControl in the license. See outputControlValue section for details. Yes, if bbOutputControlFlags is specified
bbOutputControlObligation

A comma separated list of 3 strings indicating the technology ID, the parameter name, and the parameter value. Any number can be provided. When the technology is SecureContentPath and the parameter name is SecurityClass, the value is a . separated list of 3 strings: – base64 encoded content ID ASCII encoding is used for contentId prior to base64 encoding – an int representing the "portions" – base64 encoded predicate byte array See the OutputControl Specification 1.0.3+ Examples: outputControlObligation=SecureContentPath, DefaultSecurityClass,0

outputControlObligation=SecureContentPath,
SecurityClass,<base64 contentid>
.<int portion>.<base64 predicate>
No
bbOutputControlOverride A comma separated list of 3 strings indicating the technology ID, the parameter name, and the parameter value. Any number can be provided. See above for SecureContentPath handling. No
bbRentalPeriodEndTime 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 license is issued that the license will be valid. The content cannot be played after this time. Only valid if rightsType is Rental. Rental date cannot exceed 5555-12-31T12:00:00Z Yes, when rightsType is Rental.
marlinms3:
Query Parameter Description Required?
ms3ControlFlags MS3 Control Flags, as a 1-byte hex value. If specified, it can’t be an empty string. No
ms3DeviceId A string to represent the Device id to which to bind token. No
ms3OutputControlFlags MS3 Output Control Flags, as a 4-byte hex value. Must be provided if ms3OutputControlValue is specified. If specified, it can’t be an empty string. No
ms3OutputControlValue MS3 Output Control Value, as a 4-byte hex value. Must be provided if ms3OutputControlFlags is specified. If specified, it can’t be an empty string. No
ms3ExtensionData A short form wrapping extensionType, extensionCriticalFlag, and extensionPayload, as a comma separated string. See format below. Example: "ms3ExtensionData":["wudo,false,payload1"] No, any number can be provided
fp:
Query Parameter Description Required?
fpDeviceId A string to represent the Device id to which to bind token. No
fpIv A 16 byte hexadecimal string representation of the content encryption IV. If not set, it will default to all ‘0s’. No
fpRentalDuration Duration of the rental in seconds (default – 0) No
fpExtensionData A short form wrapping extensionType and extensionPayload, as a comma separated string. See format below. Example: "fpExtensionData":["fex1,payload1","fex2,payload2"] No, any number can be used
pr:
Query Parameter Description Required?
prDeviceId A 16 byte hexadecimal string to represent the Device id to which to bind token. No
prMinCertSecurityLevel Security level (0-3000) No
prRightsType Specifies the kind of rights. Must be BuyToOwn or Rental. No
prRentalPeriodEnd 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 prRightsType is Rental. Yes, when prRightsType is Rental.
prRentalPlayDuration Time, in seconds, that the content can be played once play has started. Only valid if rightsType is Rental. No
prAnalogVideoOPL Integer value to indicate the Output Protection Level for analog video. Valid range 0-999. No
prCompressedDigitalAudioOPL Integer value to indicate the Output Protection Level for compressed digital audio. Valid range 0-999. No
prCompressedDigitalVideoOPL Integer value to indicate the Output Protection Level for compressed digital video. Valid range 0-999. No
prUncompressedDigitalAudioOPL Integer value to indicate the Output Protection Level for uncompressed digital audio. Valid range 0-999. No
prUncompressedDigitalVideoOPL Integer value to indicate the Output Protection Level for uncompressed digital video. Valid range 0-999. No
prUnknownOutputBehavior Required behaviour when the output is unknown. Allowed values: ‘Allow’, ‘Disallow’ or ‘SDOnly’ No
prOutputControlFlags A 4-byte hex value to indicate the flags for other output control options No
prAppRestriction Size of application restriction (max size of 255 characters) No
prExtensionData A short form wrapping extensionType and extensionPayload, as a comma separated string. See format below. Example: "prExtensionData":["pex1,payload1","pex2,payload2"] No, any number can be used
wv:
Query Parameter Description Required?
wvContentId Content Id for Widevine. Max length is 36 bytes. No
wvDeviceId A string to represent the Device id to which to bind token. No
wvTrackTypes Allowed values are 0-4. (Default = 1) 0 = SD, 1 = HD, 2 = AUDIO, 3 = UHD1, 4 = UHD2 Any number of these can be provided, but a matching number of kid parameters must be provided. If multiple track types are supplied, the parameters are to be provided as an array. No
wvSecurityLevels Allowed values are 1-5. (Default = 1) 1 = SW_SECURE_CRYPTO, 2 = SW_SECURE_DECODE 3 = HW_SECURE_CRYPTO, 4 = HW_SECURE_DECODE 5 = HW_SECURE_ALL Any number of these can be provided, but a matching number of kid parameters must be provided. The parameters are to be provided as an array. No
wvHdcpOutputControls Allowed values are 0-5. (Default = 0) 0 = HDCP_NONE, 1 = HDCP_V1, 2 = HDCP_V2 3 = HDCP_V2_1, 4 = HDCP_V2_2 5 = HDCP_NO_DIGITAL_OUTPUT Any number of these can be provided, but a matching number of kid parameters must be provided. The parameters are to be provided as an array. No
wvCgmsFlagsOutputControls Allowed values are 0, 1, 2, 3. (Default = 0) 0 = CGMS_NONE, 1 = CGMS_FREE, 2 = CGMS_ONCE, 3 = CGMS_NEVER Any number of these can be provided, but a matching number of kid parameters must be provided. The parameters are to be provided as an array. No
wvDisableAnalogOutput Allowed values are 0, 1. (Default = 0) Indicates whether analog output is allowed. 0 = DISABLE_ANALOG_OUTPUT_FALSE, 1 = DISABLE_ANALOG_OUTPUT_TRUE Any number of these can be provided, but a matching number of kid parameters must be provided. The parameters are to be provided as an array. No
wvHdcpSrmRule Allowed values are 0, 1. (Default = 0) Use CURRENT_SRM to not allow this key if the device has an older SRM and cannot support SRM updates. 0 = HDCP_SRM_RULE_NONE, 1 = CURRENT_SRM Any number of these can be provided, but a matching number of kid parameters must be provided. The parameters are to be provided as an array. No
wvLicenseDuration Duration of the license in seconds. If not provided, it indicates that there is no limit to the duration. Please check note below for detailed information. No
wvPlaybackDuration The viewing window of time once playback starts within the license duration. If not provided, it indicates that there is no limit to the duration. No
wvExtensionData A short form wrapping extensionType and extensionPayload, as a comma separated string. See format below. Example: "wvExtensionData":["wex1,payload1","wex2,payload2"] No, any number can be used

Note about wvLicenseDuration:

  1. Playback will stop wvLicenseDuration seconds after beginning of playback.
  2. To allow playback to be stopped/resumed for an unlimited amount of time, omit wvLicenseDuration (it will default to infinite). Otherwise specify the amount of time during which end-users should be able to enjoy the stream

14.4   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error. text/uri-list License acquisition url + 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

The response of the ExpressPlay REST API for Universal License Token Request is of type text/uri-list containing the license acquisition url + license token as a ExpressPlayToken query parameter.

For example:

14.5   Example of a token request:

curl -X POST -H "Content-type: application/json" ‘https://ut.{prod_domain}/hms/ut/token?customerAuthenticator=CUSTOMER_AUTHENTICATOR&errorFormat=json’ -d @utRequest.json

14.6   Example of a license request using Universal Token for Widevine using curl:

curl -X POST -H "utoken-drm : wv" -H "Content-type: application/octet-stream" ‘https://ut.{prod_domain}/hms/ut/rights/?ExpressPlayToken=AQAAAJJ2Y0MAAABQbyvnJ6KgEg_w-2yZmU-MsjTEZ3f7UkhUcFhDFAvdonzBkRGQU-xe1G-DMbel5-BVH_PozovdWhKZx0_SXRokfh9-FERmBl6OEfGfPqMI1eO1PqRkx59Q2q1s2cFNrqfml8Y3RQ’ –data-binary @requestdata.bin

Note: Depending on the value of the errorFormat parameter, the response will either be of Content-Type text/html or application/json. In the case of text/html, the message, formatted as HTML will provide an error code and error message in human-readable format.Error codes will be negative integer values. Currently defined error codes are:

15   A/B Manifest Generation

Purpose
Generate a content manifest with a watermark derived from manifests of A/B rendering of the content (See ExpressPlay watermarking SDK for details)
URLs
HLS
https://wm.service.expressplay.com/wm/manifest/hlsca
DASH
https://wm.service.expressplay.com/wm/manifest/dashca
Method
POST

15.1   Query parameters

Property Description Required?
customerAuthenticator API key for production environment Yes
pacePayloadSize Has to match the payload size specified during pace file generation. Value has to equal 8, 16, 24, or 32 Yes
tryCache

Value can be either true or false, if not specified assumed to be false.

If value is true then the MD5 hash values will be used to retrieve the A & B manifest from the ExpressPlay service cache.

No
forceCache

Value can be either true or false, if not specified assumed to be false.

If value is true then the A & B manifests will be cached by the ExpressPlay service cache and can be referenced by their MD5 hash values in subsequent calls.

No
decisionList

Value can be either true or false, if not specified assumed to be false.

If value is true then an array containing a sequence of 0 an 1 item is returned.:

  • A value of 0 indicates a segment from manifest A is selected
  • A value of 1 indicates a segment from manifest B is selected
No

15.2   Request body

JSON encoded object with the following properties:

Property Description Required?

manifests

Array of JSON objects with the following properties:

manifestA: Base64 encoding of HLS manifest A [required]

manifestB: Base64 encoding of HLS manifest B [required]

manifestA_hash: MD5 hash of the UTF-8 manifest A [required]

manifestB_hash: MD5 hash of the UTF-8 manifest B [required]

Yes

pace

Pace file generated by the ExpressPlay watermarking tools, encoded in base64

Yes

pace_hash

MD5 hash of the UTF-8 pace file

Yes

hash_prefix

Custom prefix to append to MD5 hash of manifest (used to uniquely identify manifest in cache)

No

15.3   Response

HTTP Status Code Description Content-Type Entity Body Contains

200 OK

Request succeeded

application/json

JSON response

400 Bad Request

Request contained invalid values/parameters

application/json

JSON with error description

15.3.1   Successful Response Body

JSON encoded object with the following properties:

Property Description

wm_token

manifest ID token to be used in license request (format is ‘wmid’ + manifest_id)

manifest_id

unique watermark ID for response manifest, integer value between 1-8388607 (1-0x7fffff)

decisionList

watermark decision list, array of 1/0 sequence (included only if decisionList parameter is true)

manifests:

Array of objects with the following properties (included only if decisionList parameter is false)

– manifest: Base64 encoding of interleaved HLS manifest

– manifest_hash: MD5 hash of the UTF-8 interleaved HLS manifest

– manifestA_hash: MD5 hash of the request UTF-8 manifest A

– manifestB_hash: MD5 hash of the request UTF-8 manifest B

15.3.2   Failed Response

JSON encoded object with the following properties:

Property Description

error

Error code matching one of the entries below

message

Explanation of error cause

15.3.3   Error Codes

Code Description
-2017 Customer authenticator must be supplied
-2018 Customer authenticator invalid
-3200 Invalid HTTP method
-3201 Watermark service not enabled for customer authenticator specified
-3210 Malformed request body or invalid JSON
-3211 Manifests array not specified
-3212 Manifest pairs not specified or invalid set of manifests
-3213 Invalid manifest
-3214 Manifest hash not specified
-3215 Manifest hash does not match
-3216 Manifest content IDs do not match
-3217 Multiple manifests supplied for DASH
-3218 Missing or invalid content ID
-3219 Manifest cache miss
-3300 Unknown API
-3400 Unknown error

16   Event Error Codes

Code Description
-2001 Invalid token version
-2002 Invalid token expiration time: <details>
-2003 Invalid IP address
-2005 Invalid content encryption key: <details>
-2006 Mismatch in number of content IDs and content keys specified
-2007 Invalid control flags specified: <details>
-2008 Invalid output control flags specified: <details>
-2009 Invalid output control value specified: <details>
-2013 Invalid action token type: <details>
-2014 Missing action token type
-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. IMPORTANT: 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
-2026 Missing content ID
-2027 Content encryption key must be 32-hexadecimal digits long
-2029 Invalid content ID
-2030 ExpressPlay Admin error
-2031 Service Account Disabled
-2032 Invalid MS3 Token Type
-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
-2038 Extension critical flag should be true or false
-2039 OutputControlFlags and OutputControlValue are inconsistent
-2040 OutputControlFlag must be encode 4 bytes
-2041 OutputControlValue must encode 4 bytes
-2045 Only one of ms3Scheme or ms3SchemeType can be specified
-2046 Invalid ms3SchemeType value
-2048 Log content info flag should be true or false
-2053 Invalid content type specified
-2054 Invalid cfid length specified
-2055 Invalid cfid specified
-2056 Invalid active user id length specified
-2057 Unauthorized service specified
-2058 Request parameters specified are unacceptable
-2059 Invalid MS3Extension parameters specified
-2060 Only one content key can be specified if cfid is provided
-2145 OutputControl Params are of the form technology,param,value
-2146 Invalid SecurityClass parameter format
-2147 Use either outputControlFlags or outputControlObligation for specifying output control technologies
-2148 Invalid output control parameter for this technology
-2151 Use either outputControlOverrideId or outputControlOverride for specifying output control override technologies
-3004 Invalid error format specified: <format>
-4001 Device could not be authenticated
-4010 Invalid token
-4017 Mismatch in number of content IDs and kids specified
-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
-4023 Mismatch in number of content IDs and encrypted keys specified
-4024 Invalid encrypted key or kek
-4025 Only one of ek or kid can be provided
-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
-5008 Invalid cookie length
-6001 Invalid FPExtension parameters specified
-6002 Invalid FP Token Type
-6003 Invalid IV parameter specified
-6004 Failed to generate CKC for FP
-6005 Invalid key data specified
-6006 Service not authorized for FairPlay support
-6007 Invalid rental duration specified
-6009 FairPlay option disabled
-7001 At least one content ID must be supplied
-7003 Missing security level value
-7004 Invalid security level value
-7006 Missing HDCP output control value
-7007 Invalid license duration specified
-7008 Failed to generate Widevine license
-7009 Invalid WVExtension parameters specified
-7011 Widevine option disabled
-7012 Widevine device id mismatch
-7013 Invalid playback duration specified
-7014 Invalid CGMS flags output control specified
-7015 Mismatch in number of kids and content keys specified
-7018 Mismatch in number of track types specified
-7019 Invalid track type specified
-7020 Mismatch in number of security levels specified
-7021 Invalid track type specified
-7022 Mismatch in number of cgms flags output control specified
-7023 Invalid content id length specified
-7024 Mismatch in number of content key specified
-7025 Invalid disable analog output specified
-7026 Invalid hdcp srm rule specified
-7027 Mismatch in number of disable analog outputs specified
-7028 Mismatch in number of hdcp srm rules specified

17   JSON Errors

API responses have the following structure for error data. Error codes will be negative integer values.

{
  "valid": false,
   "events": [],
   "error": {
     "message": <error_message>,
     "code": <error_code>
   }
 }

18   General Error Codes

The following error codes may appear across the service API.

Code Description
-9000 Missing customer authenticator
-9001 Corrupted customer authenticator
-9002 No such service/invalid customer authenticator
-9003 Invalid customer authenticator
-9004 No lookup method (currently unused)
-9005 Invalid version specified
-9006 Invalid type specified. This occurs when the "type" parameter is specified in the /cmiapi/getrecord API and the value is not either "ms3" or "bb".
-9009 Invalid value for start parameter. This value must be a positive integer. If a value less than 1 is supplied, this parameter will be assumed to be 1.
-9010 Invalid value for length parameter. This value must be a positive integer less or equal to 200. If a value greater than 200 is supplied, this parameter will be assumed to be 200.
-9011 Invalid value for id parameter. This value must be a positive integer. If a value less than 1 is supplied, this parameter will be assumed to be 1.
-9012 Failed to get data
-9013 Missing startTime parameter
-9014 Invalid startTime parameter
-9015 Missing endTime parameter
-9016 Invalid endTime parameter
-9017 Invalid page parameter
-9018 Invalid size parameter