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 |