REST API Documentation

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

For backward compatibility with legacy URLs (from the previously named Hosted Marlin Service), ExpressPlay will continue to accept the following legacy host names for use with Marlin token and record retrieval APIs:

LEGACY PRODUCTION HOSTS:
ms3-gen.service.hostedmarlin.com
bb-gen.service.hostedmarlin.com
cmi.service.hostedmarlin.com
LEGACY TEST HOSTS:
ms3-gen.eval.hostedmarlin.com
bb-gen.eval.hostedmarlin.com
cmi.eval.hostedmarlin.com

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 most recent 32 events matching this cookie. This may not be used in combination with other querying methods.
  3. If an integer 'id' is specified, the event matching the given id is returned. (See "event_id" below.)
  4. If integers 'start' and 'length' are specified, this API returns records matching that range. The parameter 'start' is the offset, and 'length' is the number of records returned, providing a window of records. This may be iteratively called to retrieve all known records. Note that 'start' does not refer to an event_id, but rather a 0-based index of all records for a service. To progressively obtain all records, a caller would request (start=0, length=200), then (start=200, length=200) and so forth until no more records are returned.
Using more than one method simultaneously in a request is unsupported.

URLs

Production: https://api.{prod_domain}/cmiapi/getrecord/

Test: https://api.test.expressplay.com/cmiapi/getrecord/

Method

GET, POST (with www-url-encoded body containing parameters for both the methods)

 

2.1   Request Parameters

Query Parameter Description Required?
apiVersion Version number. If supplied, must be 0. No
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 or "pr" for PlayReady. 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. For 'pr', cookie is the value of the 'kid' used in PlayReady token generation 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
descending Specifies the order of records returned. Is only valid when neither cookie nor id parameters are supplied. May be either "true" or "false". "1" or "0" may also be used. The default is "false" when start/length are not specified and true, when neither start nor length is specified. This is only valid for 'bb' and 'ms3'. For 'pr' it is always sorted by date. No
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 and ms3

Field Type Description
event_id integer ExpressPlay-assigned ID number for this record.
type string Type of transaction. One of 'ms3License', 'bbLicense', 'bbNodeAcquisition', 'bbLinkAcquisition', 'bbAgentExecutionNotification', 'bbUnLink'.
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.
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_type string MS3 extension type. Exists only in MS3 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 extension payload. Exists only in MS3 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. Exists only in BB token redemption. 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. Exists only in BB token redemption. 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. Exists only in BB token redemption
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.

2.6   Events Fields for PlayReady

Field Type Description
event_id GUID Service-assigned ID number for this record.
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

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

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, POST (with www-url-encoded body containing parameters for both the methods)

3.1   Request Parameters

Query Parameter Description Required?
apiVersion Version number. If supplied, must be 0. No
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. Records returned will be of this type. Defaults to "ms3" if not specified. No
startTime The value MUST be a string in RFC 3339 _ date/time format in the 'Z' zone designator ("Zulu time"). An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. startTime shouldn't greater than 30 days from current time. Yes
endTime The value MUST be a string in RFC 3339 _ date/time format in the 'Z' zone designator ("Zulu time"). An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. This time shouldn't be greater than current time and less than startTime. Yes
page Page number. Defaults to page 0 (first page) Page is a 0-based index. No
size Requested items on each page. Defaults to 200 if not provided. Size is limited to 2000 records. No

3.2   Example Queries

Production:

https://api.{prod_domain}/cmiapi/getrecordbytime?customerAuthenticator=553,d31ab64f35724f69beb177f0c3d01e41a&type=ms3

Test:

https://api.test.expressplay.com/cmiapi/getrecordbytime?customerAuthenticator=553,d31cd34f35724f69beb177f0c3d01e41a&type=bb

3.3   HTTP Response

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

The response will be of Content-Type application/json. Refer to 'Events Fields for bb and ms3' 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 and ms3' table for bb and ms3. 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

Purpose

Queries ExpressPlay to provide customer token credits remaining in the account

URLs

Production: https://api.{prod_domain}/cmiapi/getaccountinfo/

Test: https://api.test.expressplay.com/cmiapi/getaccountinfo/

Method

GET, POST (with www-url-encoded body containing parameters for both the methods)

4.1   Request Parameters

Query Parameter Description Required?
apiVersion Version number. If supplied, must be 0. No
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes

4.2   Example Queries

Production:

https://api.{prod_domain}/cmiapi/getaccountinfo?customerAuthenticator=553,d31ab64f35724f69beb177f0c3d01e41a

Test:

https://api.test.expressplay.com/cmiapi/getaccountinfo?customerAuthenticator=553,d31cd34f35724f69beb177f0c3d01e41a

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

4.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
service_id Contains the unique id for the service. Yes
service_short_name Contains the customer's service short name Yes
remaining_tokens Contains the token credits remaining in the account. Same as num_trial_tokens but old name kept for compatibility. Yes
num_trial_tokens Contains the number of trial tokens remaining for this service. This value will be decremented during token redemptions until it is 0, after which time the appropriate count will be incremented. Yes
tokens_redeemed The number of non-Express tokens redeemed. Note: if there are trial tokens remaining (see num_trial_tokens) then these are decremented before tokens_redeemed is incremented. Yes
tokens_redeemed_bundled The number of bundled Express tokens redeemed. Note: if there are trial tokens remaining (see num_trial_tokens) then these are decremented before tokens_redeemed_bundled is incremented. Yes
tokens_redeemed_unbundled The number of unbundled Express tokens redeemed. Note: if there are trial tokens remaining (see num_trial_tokens), then these are decremented before tokens_redeemed_unbundled is incremented.  

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

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 "false", suppress contentURL, contentUrlAuthenticator, content ids, and content keys from being logged in the system. 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
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
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

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. No
deviceId Device id to which to bind token. This value will be the same as the NEMO node id of the client device. No

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

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

5.4   Correlation Parameters

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

5.5   Example Queries

Production:

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

Test:

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

5.6   HTTP Response

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

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

5.7   Event Error Codes

Code | Description
-2001 Invalid token version
-2002 Invalid token expiration time: <details>
-2003 Invalid IP address
-2005 Invalid content key: <details>
-2006 Mismatch in number of content IDs and content keys specified
-2007 Invalid control flags specified: <details>
-2008 Invalid output control flags specified: <details>
-2009 Invalid output control value specified: <details>
-2017 Authentication token must be supplied
-2018 Authentication token invalid: <details> Note: This can happen if the authenticator is wrong or when accessing the test API at *.test.expressplay.com using the production authenticator and vice versa. IMPORTANT: The Test SDK and Advanced Test Tool (ATT) only work with *.test.expressplay.com, whereas production devices must use *.service.expressplay.com.
-2019 Insufficient tokens available
-2026 Missing content ID
-2027 Content key must be 32-hexadecimal digits long
-2029 Invalid content ID
-2030 ExpressPlay Admin error
-2031 Service Account Disabled
-2032 Invalid MS3 Token Type
-2033 Invalid cookie
-2035 No corresponding value specified
-2036 Extension type should be 4 characters
-2037 Extension payload hsould be Base64 encoded
-2038 Extension critical flag should be true or false
-2045 Only one of ms3Schme or ms3SchemeType can be specified
-2046 Invalid ms3SchemeType value
-2048 Log content info flag should be true or false
-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

Purpose

Requests a token that can be redeemed by customer to register a broadband device. Token is in the form of a Marlin action token.

URLs

Production: https://bb-gen.{prod_domain}/hms/bb/token

Test: https://bb-gen.test.expressplay.com/hms/bb/token

Method

GET, POST (with www-url-encoded body containing parameters for both the methods)

6.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes
actionTokenType Must be 0. Signifies registration action token. Yes
errorFormat Either "html" or "json". If "html" (the default) an HTML representation of any errors is provided in the entity body of the response. If "json" is specified, a structured response in json format is returned. See JSON Errors for details. The mime type of the response will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

6.2   Registration Parameters

Query Parameter Description Required?
userId An id used to uniquely identify a user. This can be any value generated and managed by the requestor that uniquely identifies an end user. Yes
userKey The hexadecimal representation of a 16-byte seed value that ExpressPlay uses to generate a key to protect content keys in user-bound licenses. This value is should be generated, hard to guess, and permanently associated with the corresponding userId. Broadband license token requests for user-bound licenses will need to specify this same value (and userId). Yes
registrationEndTime Registration end date. This value MUST be in the 'RFC 3339' _ date/time format in the 'Z' zone designator ("Zulu time") format or an integer preceded by a + sign. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the registration. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is an integer preceded by a + sign, it is taken as a relative number of seconds from the time the registration is issued that the registration will be valid. 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. 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

Purpose

Requests a token that can be redeemed by customer for a broadband license. Token is in the form of a Marlin action token.

URLs

Production: https://bb-gen.{prod_domain}/hms/bb/token

Test: https://bb-gen.test.expressplay.com/hms/bb/token

Method

GET, POST (with www-url-encoded body containing parameters for both the methods)

7.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes
actionTokenType Must be 1. Signifies license action token. Yes
errorFormat Either "html" or "json". If "html" (the default) an HTML representation of any errors is provided in the entity body of the response. If "json" is specified, a structured response in json format is returned. See JSON Errors for details. The mime type of the response will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

7.2   License Parameters

Query Parameter Description Required?

contentId

contentId.N

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

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 "false", suppress content ids, and content keys from being logged in the system. 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. 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
outputControlOverrideId Unique identifier for output control technology. A string id, for example "urn:marlin:organization:intertrust:wudo". Must not contain ' ', '\', '', '&', '<', '>', '[', ']', '^', '`', '{', '|', '}', '~'. No
outputControlOverrideParameter A string parameter name, for example "ImageConstraintLevel". Valid if outputControlOverrideId is specified. Must not contain ' ', '\', '', '&', '<', '>', '[', ']', '^', '`', '{', '|', '}', '~'. Yes, if outputControlOverrideId is present
outputControlOverrideValue An integer value. for example 0. Valid if outputControlOverrideParameter is specified. Yes, if outputControlOverrideParameter is present

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. No
deviceId Device id to which to bind token. This value will be the same as the NEMO node id of the client device. No

7.4   Correlation Parameters

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

7.5   outputControlFlags:

bit vector of flags indicating which fields are signalled in the outputControlValue. When a flag in this vector is set to 1, the Client SHALL set the output control parameters as specified by the corresponding bit-field in the outputControlValue.

Flag Bit (0 is the least significant bit) Output Control Technology Field name
0 BasicCCI DigitalOnlyToken
1 BasicCCI EPN
2 BasicCCI CCI
3 BasicCCI ImageConstraintToken
4 BasicCCI APS
5 DTCP RetentionMoveMode
6 DTCP RetentionState
7 DTCP EPN
8 DTCP DTCP_CCI
9 DTCP ImageConstraintToken
10 DTCP APS

7.6   outputControlValue:

bit fields indicating the value of zero or more output control fields.The fields are encoded as follows:

Bit range (0 is the least significant bit) Output Control Technology Field name
0 BasicCCI DigitalOnlyToken
1.4 BasicCCI Reserved
5 BasicCCI EPN
6.7 BasicCCI CCI
8 BasicCCI ImageConstraintToken
9.10 BasicCCI APS
11 DTCP RetentionMoveMode
12..14 DTCP RetentionState
15 DTCP EPN
16..17 DTCP DTCP_CCI
18 DTCP ImageConstraintToken
19..20 DTCP APS

7.7   HTTP Response

HTTP Status Code Description Content-Type Entity Body Contains
200 OK No error.
application/vnd.marlin.
drm.actiontoken+xml
 License Action Token
400 Bad Request Invalid args text/html or application/json Error description
401 Unauthorized Auth failed text/html or application/json Error description
404 Not found Bad URL text/html or application/json Error description
50x Server Error Server error text/html or application/json Error description

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

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

7.8   Event Error Codes

Code Description
-2001 Invalid token version
-2002 Invalid token expiration time: <details>
-2003 Invalid IP address
-2005 Invalid content key: <details>
-2006 Mismatch in number of content IDs and content keys specified
-2008 Invalid output control flags specified: <details>
-2009 Invalid output control value specified: <details>
-2010 Invalid user key: <details>
-2011 Missing user key
-2013 Invalid action token type: <details>
-2014 Missing action token type
-2017 Authentication token must be supplied
-2018 Authentication token invalid: <details> Note: This can happen if the authenticator is wrong or when accessing the test API at *.test.expressplay.com using the production authenticator and vice versa. IMPORTANT: The Test SDK and Advanced Test Tool (ATT) only work with *.test.expressplay.com, whereas production devices must use *.service.expressplay.com.
-2019 Insufficient tokens available
-2020 Missing rights type
-2021 Invalid rights type
-2022 Missing rental period end time
-2023 Missing rental play duration
-2025 Invalid rental play duration
-2026 Missing content ID
-2027 Content key must be 32-hexadecimal digits long
-2029 Invalid content ID
-2030 ExpressPlay Admin error: <details>
-2031 Service Account Disabled
-2033 Invalid cookie
-2034 Invalid Output Control, values out of specified range
-2035 No corresponding value specified
-2039 OutputControlFlags and OutputControlValue are inconsistent
-2040 OutputControlFlag must be encode 4 bytes
-2041 OutputControlValue must encode 4 bytes
-2042 Invalid outputControlOverrideId
-2043 Invalid outputControlOverrideParameter
-2048 Log content info flag should be true or false
-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

Purpose

Requests a token that can be redeemed by customer to deregister a broadband device. Token is in the form of a Marlin action token.

URLs

Production: https://bb-gen.{prod_domain}/hms/bb/token

Test: https://bb-gen.test.expressplay.com/hms/bb/token

Method

GET, POST (with www-url-encoded body containing parameters for both the methods)

8.1   Token Parameters

Query Parameter Description Required?
customerAuthenticator API key for each customer. Both the production and test customerAuthenticator can be found in the ExpressPlay Admin dashboard. Yes
actionTokenType Must be 2. Signifies deregister action token. Yes
errorFormat Either "html" or "json". If "html" (the default) an HTML representation of any errors is provided in the entity body of the response. If "json" is specified, a structured response in json format is returned. See JSON Errors for details. The mime type of the response will be as either "text/uri-list" on success, "text/html" for "html" error format, or "application/json" for "json" error format. No

8.2   Deregistration Parameters

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

8.3   Token Restriction Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST a string in RFC 3339 date/time format in the 'Z' zone designator ("Zulu time") or an integer preceded by a + sign. If the value is a string in RFC 3339 date/time format, then it represents an absolute expiration date/time for the token. An example of an RFC 3339 date/time is 2006-04-14T12:01:10Z. If the value is an integer preceded by a + sign,then it is interpreted as a relative number of seconds, from issuance, that the token is valid.For example,+60 specifies one minute. The maximum and default(if not specified) token lifetime is 30 days. 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

Purpose

Requests a token that can be redeemed by customer for a PlayReady license. The response is a JSON payload that contains two fields:

“licenseAcquisitionUrl" and “token". More information about the use of PlayReady tokens in devices can be found here.

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

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. No
deviceId A 16 byte hexadecimal string to represent the Device id to which to bind token. No

9.4   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

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:

./developer.htmlplayready-apps

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

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

9.5   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 hsould 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

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

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".
-9007 Invalid value for superfast parameter specified. This parameter can be specified in the /cmiapi/getrecord API. It must be either 0 (not superfast) or 1 (superfast).
-9008 Use of superfast parameter requires specification of cookie. If, in the /cmiapi/getrecord API you enable superfast queries by setting superfast=1, then you must also specify the cookie parameter.
-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