FairPlay license token request and response

Last update: 2023-10-02

The FairPlay license token interface provides production and test services. This request returns a token that can be redeemed for a FairPlay license.

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

URLs:

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

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

  • Sample request:

  https://fp-gen.test.expressplay.com/hms/fp/token?customerAuthenticator=
   <ExpressPlay customer authenticator identifier>
   &kid=<CEKSID>
   &contentKey=<CEK>
   &rightsType=BuyToOwn
   &analogVideoOPL=0
   &compressedDigitalAudioOPL=0
   &compressedDigitalVideoOPL=0
   &uncompressedDigitalAudioOPL=0
   &uncompressedDigitalVideoOPL=0

  • Sample Response:

    https://fp.service.expressplay.com:80/hms/fp/rights/?ExpressPlayToken=<base64-encoded ExpressPlay token>

Request Query Parameters

Table 3: Token Query Parameters

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

Table 4: License Query Parameters

Query Parameter Description Required?
generalFlags A 4 byte hexadecimal string representing the license flags. ‘0000’ is the only allowed value. No
kek Key Encryption Key (KEK). Keys are stored encrypted with a KEK using a key wrapping algorithm (AES Key Wrap, RFC3394). If kek is supplied, either one of the kid or the ek parameters needs to be supplied, but not both. 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. 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 the kek and ek or kid are provided.
iv A 16 byte hexadecimal string representation of the content encryption IV Yes
rentalDuration Duration of the rental in seconds (default - 0) No
fpExtension A short form wrapping extensionType and extensionPayload, as a comma separated string. For example: […] &fpExtension=wudo,AAAAAA==&[…] No, any number can be used

Table 5: Token Restriction Query Parameters

Query Parameter Description Required?
expirationTime Expiration time of this token. This value MUST be 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

Table 6: Correlation Query Parameters

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

Response

Table 7: HTTP Responses

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

Table 8: Event Error Codes

Code Description
-2002 Invalid token expiration time: <details>
-2003 Invalid IP address
-2005 Invalid content encryption key: <details>
-2008 Invalid output control flags specified: <details>
-2017 Authentication token must be supplied
-2018 Authentication token invalid: <details>

Note: This can happen if the authenticator is wrong or when accessing the test API at *.test.expressplay.com using the production authenticator and vice versa.

Note: The Test SDK and Advanced Test Tool (ATT) only work with *.test.expressplay.com , whereas production devices must use *.service.expressplay.com .

-2019 Insufficient tokens available
-2020 Missing rights type
-2021 Invalid rights type
-2022 Missing rental period end time
-2023 Missing rental play duration
-2025 Invalid rental play duration
-2027 Content encryption key must be 32-hexadecimal digits long
-2030 ExpressPlay Admin error: <details>
-2031 Service Account Disabled
-2033 Invalid cookie
-2034 Invalid Output Control, values out of specified range
-2035 No corresponding value specified
-2036 Extension type should be 4 characters
-2037 Extension payload should be Base64 encoded
-2040 OutputControlFlag must be encode 4 bytes
-3004 Invalid error format specified: <format>
-4001 Device could not be authenticated
-4010 Invalid token
-4018 Missing Kid
-4019 Failed to get content key from key storage service
-4020 kid must be 32 hexadecimal characters long
-4021 kid must be 64 characters long after the ^
-4022 Invalid kid
-4024 Invalid encrypted key or kek
-5003 Invalid general flags
-6001 Invalid FPExtension parameters specified
-6002 Invalid FP Token Type
-6003 Invalid iv parameter specified
-6004 Failed to generate CKC for FP
-6005 Invalid key data specified
-6006 Service not authorized for FairPlay support
-6007 Invalid rental duration specified
-6008 Device ID binding is not supported for FairPlay
-6009 FairPlay option disabled
Previous page
Next page

On this page