Developers     Developer center

Developer center

under hero banner

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

Note: The getrecord API is intended to be used for trouble-shooting purpose only and it should not be used in a production workflow. A faster/lower latency version of this api suitable for production workflow is available at additional cost. Please contact your account manager or [email protected] for details.
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 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 or “wv” for Widevine. 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

Note: The customerAuthenticator parameter can also be passed in an HTTP header (i.e. ‘customerAuthenticator: 863255912,62981eb9f1ef49d5893d71bee6181735’)

 

2.2   Example Queries

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

 

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 and wv

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’ and ‘wvLicense’
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

 

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)
content_key_hash string Only one hash is given, no matter how many keys were in content.

 

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 or “wv” for Widevine. 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

Note: The customerAuthenticator parameter can also be passed in an HTTP header (i.e. ‘customerAuthenticator: 863255912,62981eb9f1ef49d5893d71bee6181735’)

 

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’ 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 and wv’ table for bb, ms3, fp and wv. 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

Note: The customerAuthenticator parameter can also be passed in an HTTP header (i.e. ‘customerAuthenticator: 863255912,62981eb9f1ef49d5893d71bee6181735’)

 

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’ 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

Note: For MS3, contentId is not mandatory when kid/kek are provided in the token request. The MS3 service computes the contentId as the implicit content ID per Marlin spec, as “urn:marlin:kid:” + KID,. If your content IDs differ from this pattern, as for instance when using Marlin BBTS content IDs, the contentId parameter has to be specified explicitly.

 

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
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
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.

 

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
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, analogVideoOPL.N Integer value to indicate the Output Protection Level for analog video. Any number of these can be provided to represent for each track. If a single analogVideoOPL is supplied, the parameter analogVideoOPL can be used. If multiple of these are supplied, the parameters should be named analogVideoOPL.0, analogVideoOPL.1, etc. Note that numbering 0-based (the first analogVideoOPL should be analogVideoOPL.0). The values allowed by Microsoft are: 100, 150, 200 No
compressedDigitalAudioOPL, compressedDigitalAudioOPL.N Integer value to indicate the Output Protection Level for compressed digital audio. Any number of these can be provided to represent for each track. If a single compressedDigitalAudioOPL is supplied, the parameter compressedDigitalAudioOPL can be used. If multiple of these are supplied, the parameters should be named compressedDigitalAudioOPL.0, compressedDigitalAudioOPL.1, etc. Note that numbering 0-based (the first compressedDigitalAudioOPL should be compressedDigitalAudioOPL.0). The values allowed by Microsoft are: 100, 150, 200, 250, 300 No
compressedDigitalVideoOPL, compressedDigitalVideoOPL.N Integer value to indicate the Output Protection Level for compressed digital video. Any number of these can be provided to represent for each track. If a single compressedDigitalVideoOPL is supplied, the parameter compressedDigitalVideoOPL can be used. If multiple of these are supplied, the parameters should be named compressedDigitalVideoOPL.0, compressedDigitalVideoOPL.1, etc. Note that numbering 0-based (the first compressedDigitalVideoOPL should be compressedDigitalVideoOPL.0). The values allowed by Microsoft are: 400, 500 No
uncompressedDigitalAudioOPL, uncompressedDigitalAudioOPL.N Integer value to indicate the Output Protection Level for uncompressed digital audio. Any number of these can be provided to represent for each track. If a single uncompressedDigitalAudioOPL is supplied, the parameter compressedDigitalVideoOPL can be used. If multiple of these are supplied, the parameters should be named uncompressedDigitalAudioOPL.0, uncompressedDigitalAudioOPL.1, etc. Note that numbering 0-based (the first uncompressedDigitalAudioOPL should be uncompressedDigitalAudioOPL.0). The values allowed by Microsoft are: 100, 150, 200, 250, 300 No
uncompressedDigitalVideoOPL, uncompressedDigitalVideoOPL.N Integer value to indicate the Output Protection Level for uncompressed digital video. Any number of these can be provided to represent for each track. If a single uncompressedDigitalVideoOPL is supplied, the parameter uncompressedDigitalVideoOPL can be used. If multiple of these are supplied, the parameters should be named uncompressedDigitalVideoOPL.0, uncompressedDigitalVideoOPL.1, etc. Note that numbering 0-based (the first uncompressedDigitalVideoOPL should be uncompressedDigitalVideoOPL.0). The values allowed by Microsoft are: 100, 250, 270, 300 No
unknownOutputBehavior Required behavior when the output is unknown. Allowed values: ‘Allow’, ‘Disallow’ or ‘SDOnly’ Default is ‘Disallow’. No
minCertSecurityLevel, minCertSecurityLevel.N Security level (150, 2000, 3000. Default is 2000. Any number of these can be provided to represent for each track. If a single minCertSecurityLevel is supplied, the parameter minCertSecurityLevel can be used. If multiple of these are supplied, the parameters should be named minCertSecurityLevel.0, minCertSecurityLevel.1, etc. Note that numbering 0-based (the first minCertSecurityLevel should be minCertSecurityLevel.0). No
useHttps If a value of “true” is passed, license service
url will contain https in the response.
No
automaticGainControlAndColorStripe, automaticGainControlAndColorStripe.N Valid values are 0, 1, 2 and 3. PlayReady CRs, table 6.5.1 Explicit Analog Video Output Protection GUID: {C3FD11C6-F8B7-4d20-B008-1DB17D61F2DA} Any number of these can be provided to represent for each track. If a single automaticGainControlAndColorStripe is supplied, the parameter autmaticGainControlAndColorStripe can be used. If multiple of these are supplied, the parameters should be named automaticGainControlAndColorStripe.0, automcaticGainControlAndColorStripe.1, etc. Note that numbering 0-based (the first automaticGainControlAndColorStripe should be automaticGainControlAndColorStripe.0). No
algId Valid values are ‘aescbc’ and ‘aesctr’. If the challenge has this value specified, it has to match the value passed in the token request. No
hdcpTypeRestriction, hdcpTypeRestriction.N Valid value is true. HDCP Type 1 enforced. PlayReady CRs, table 6.6.1 Explicit Digital Video Output Restriction GUID: {ABB2C6F1-E663-4625-A945-972D17B231E7} Any number of these can be provided to represent for each track. If a single hdcpTypeRestriction is supplied, the parameter hdcpTypeRestriction can be used. If multiple of these are supplied, the parameters should be named hdcpTypeRestriction.0, hdcpTypeRestriction.1, etc. Note that numbering 0-based (the first hdcpTypeRestriction should be hdcpTypeRestriction.0). Default is false. No
maximumResolutionDecode, maximumResolutionDecode.N Parameters correspond to “Maximum Frame Width in Pixels, Maximum Frame Height in Pixels” PlayReady CRs, table 6.6.1 Explicit Digital Video Output Restriction GUID: {9645E831- E01D-4FFF-8342-0A720E3E028F} integer, integer. Any value between 0 and 4294967294 are allowed for width and height Any number of these can be provided to represent for each track. If a single maximumResolutionDecode is supplied, the parameter maximumResolutionDecode can be used. If multiple of these are supplied, the parameters should be named maximumResolutionDecode.0, maximumResolutionDecode.1, etc. Note that numbering 0-based (the first maximumResolutionDecode should be maximumResolutionDecode.0). 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:

https://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.

Note about PlayReady license redemption: When redeeming the PlayReady license using the generated token, it’s mandatory to specify the ‘content-type: text/xml’ HTTP header

 

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
-5021 Invalid automatic gain control and color stripe specified
-5022 Invalid analog video output protection value specified
-5023 Invalid compressed digital audio output protection value specified
-5024 Invalid compressed digital video output protection value specified
-5025 nvalid uncompressed digital audio output protection value specified
-5026 Invalid uncompressed digital video output protection value specified
-5028 Invalid hdcp type restriction value specified
-5030 Maximum resolution decode value can only be between 0 and 4294967295
-5031 Invalid algorithm Id specified


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
playbackDuration Specifies the maximum time the license stays valid (in seconds) before playback is started (Measured from license acquisition time)

  • Requires the use of a persistent license
  • A value of 0 indicates unlimited validity.
  • The storageDuration and playbackDuration parameters must both be specified and are mutually exclusive with the rentalDuration parameter.

The playbackDuration parameter is used in conjunction with the storageDuration parameter to implement a dual expiry window for persistent licenses.

Playback must start before the duration specified in playbackDuration parmeter and is then valid for the period specified in the storageDuration parameter.

No
storageDuration Specifies the maximum time the license stays valid after playback has been started. Measured from the first playback start time

  • Requires the use of a persistent license
  • A value of 0 indicates unlimited validity.

See the documentation of playbackDuration parameter for further details

No
hdcpOutputControl 0 = HDCP not required
1 = HDCP Type 0 enforced
2 = HDCP Type 1 enforced
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, indicating infinite duration) No
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.

Note about FairPlay license redemption: When redeeming the FairPlay license using the generated token, it’s mandatory to specify ‘content-type: application/octet-stream’ HTTP header.

 

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
-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 characters. 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 the browser does not have a verified Video Media Path (VMP); specific platforms such as Linux Desktop do not have a verified VMP. Set this field to ‘true’ to allow a license request to succeed when VMP status is unverified. The default value is currently True; however, this may change in the future (Please see note below) No

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.
Google is currently allowing systems with an unverified Video Media Path (VMP) to play content but has stated this will not be the case in the future and the allowUnverifiedPlatform will default to False. Note that specific platforms such as Linux Desktop do not have a VMP and will not play back content in the future.

 

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.

Note about Widevine license redemption: When redeeming the Widevine license using the generated token, it’s mandatory to specify ‘content-type: application/octet-stream’ HTTP header

 

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
-7008xxx Failed to generate Widevine license. xxx is the Widevine error code if available.
-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 Universal License Token Request

Deprecation Notice

The Universal Token API will be deprecated on June 30th 2020, after this date only essential bug fixes will be made to the API. The API will no longer be supported after April 1, 2021.

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)

 

12.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",
       
   },
   "pr": {
       "prDeviceId": "",
       "prMinCertSecurityLevel": 2000,
       "prRightsType": "Rental",
       "prRentalPeriodEnd": "+3600",
       "prRentalPlayDuration": 3600,
       "prAnalogVideoOPL": 100,
       "prCompressedDigitalAudioOPL": 100,
       "prCompressedDigitalVideoOPL": 100,
       "prUncompressedDigitalAudioOPL": 100,
       "prUncompressedDigitalVideoOPL": 100,
       "prUnknownOutputBehavior": "Allow",
       
       "prAppRestriction": ""
  },
  "wv": {
       "wvContentId": "",
       "wvDeviceId": "",
       "wvTrackTypes": [1],
       "wvSecurityLevels": [1],
       "wvHdcpOutputControls": [1],
       "wvCgmsFlagsOutputControls": [1],
       "wvDisableAnalogOutputs": [0],
       "wvHdcpSrmRules": [0],
       "wvLicenseDuration": 36000,
       "wvPlaybackDuration": 23654656,
       
  }
}

 

12.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

 

12.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, indicating infinite duration) No
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
prAppRestriction Size of application restriction
(max size of 255 characters)
No
wv:

Query Parameter Description Required?
wvContentId Content Id for Widevine. Max length is 36 characters. 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

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

 

12.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:

 

12.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

 

12.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.


12.7   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
-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
-7008xxx Failed to generate Widevine license. xxx is the Widevine error code if available.
-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


13   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

13.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

13.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

13.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

13.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

13.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

13.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
-3220 Missing or invalid Pace file specified
-3221 Pace file hash not specified
-3222 Pace file hash does not match
-3223 Invalid Payload provided
-3224 Payload value is not divisible by 8 or exceeds 32
-3225 Pace file generated with a payload which exceeds the supplied pacePayloadSize param
-3226 Provided Pace file does not match the number of segments in the provided manifest
-3300 Unknown API
-3400 Unknown error


14   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>
   }
 }


15   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