Skip to main content

License Request Info Message

License Request Info Message is a JSON data structure designed to hold information about a DRM License Request. License Request Info Message is returned by Axinom DRM License Service as a payload of a Axinom DRM License Service Message inside a custom HTTP header X-AxDRM-Message if the return_license_request_info field in the Entitlement Message was set to true. Read Device Specific Restriction to understand how a License Request Info Message can be used.

Examples​

The following shows the structure of a License Request Info Message.

{
    "version": 1,
    "type": "widevine_license_request_info",
    "device_info": {
        "client_token": "b6dfac08-9ead-4842-aa99-4fabb6075c34",
        "device_certificate_serial_number": "29a622dd-ef79-4f8f-92be-96175a3e145d",
        "device_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1",
        "recommended_client_id": "29a622dd-ef79-4f8f-92be-96175a3e145d",
        "platform": "android",
        "widevine_cdm_version": "17.0.1@015"

    }
    "request_type": "new"
}
{
    "version": 1,
    "type": "fairplay_license_request_info",
    "device_info": {
        "device_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1",
        "recommended_client_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1",
        "supported_license_protocol_versions": [ "1", "2" ]
    },
    "license_protocol_version": "1",
    "playback_state": "new_session",
    "streaming_indicator": "requesting_device",
    "session_id": "bb529255-ee30-4d2d-b5b2-879359c6aadd"
}
{
    "version": 1,
    "type": "playready_license_request_info",
    "device_info": {
        "device_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1",
        "recommended_client_id": "82c9dbcb-277f-4792-a8ad-9cd00f4afbf1"
    }
}

Structure​

The following fields are available in the License Request Info Message:

version​

MandatoryData TypePossible Values
YesInteger1

Indicates the version of the License Request Info Message

type​

MandatoryData TypePossible Values
YesString"fairplay_license_request_info", "playready_license_request_info", "widevine_license_request_info"

Indicates the type of a License Request Info Message

device_info​

MandatoryData TypePossible Values
NoJSONDevice Info object

Encapsulates information about a device requesting a License

device_info.device_id​

MandatoryData TypePossible Values
NoStringAny string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format

Indicates the ID of a device that made a License Request.

device_info.recommended_client_id​

MandatoryData TypePossible Values
NoStringAny string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format

The recommended client identifier to use for device management. This field is intended to simplify choosing which client ID to use, as some DRMs may expose several with only specific ones being usable for certain clients. For FairPlay and PlayReady this will be the device_id. For Widevine, this will either be the client_token or the device_certificate_serial_number, chosen automatically by the license service based on the client information.

Widevine specifics: This will be set to the value of client_token in case the client has security level 3 and is one of "windows", "macos", "linux" or "chromeos". For such clients the device_ceritifcate_serial_number is not suitable for device identification as the ID can be constant for many users. NB! If the field is empty, it means that for the current platform "client ID" has to be used, but for some reason, it is not available. This should be treated as a warning that proper client identification may not be possible and that the playback application may need to be re-configured to properly support client tokens. NOTE: device_id will never be set as the recomended_client_id as the device ID is depreacted and its use is not recommended. Notify Axinom if you find a use case where the device ID is still a valid and the only usable indicator.

Supported since: Widevine API v6.21.0, FairPlay API v6.20.0, PlayReady API v6.20.0

device_info.client_token​

MandatoryData TypePossible Values
NoStringAny string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format

Widevine only. Contains the client token, which the client is currently using, or in the absence of an existing token, a new token, which has been generated by the license service and sent to the client in the license. This token can persist on the client between playback sessions and can be used to uniquely identify the client (e.g. desktop browser). If the client doesn’t support client tokens, this field is missing.

Token persistence: when using EME clients it is important to understand that client tokens only persist in case access to the key system is requested with a configuration that has persistentState set to required. Otherwise every license request yields a new client token.

device_info.device_certificate_serial_number​

MandatoryData TypePossible Values
NoStringAny string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format

Widevine only. Indicates the Widevine DRM device certificate serial number of the device that made the License Request. This is a GUID representation of the actual DRM client device certificate serial number. The serial number should be quite constant and unique in case of native players applications. L1 and L3 CDMs on a particular device likely to have different serial numbers. So if a player were to switch between them, the serial could change to the one or the other. In case of Android browsers the serial can additionally change when the browser app data is cleared or the browser is reinstalled. Browser cache clearing doesn’t seem to affect on Android. Also, on Android, different browser on the same device may have different serials.

device_info.platform​

MandatoryData TypePossible Values
NoStringPossible values include: android, chromecast,chromeos, fireos, ios, linux, macos, OEM, other, PLATFORM_UNSPECIFIED, playstation, rdk, roku, tizen, webos, windows, WindowsOnArm, WindowsOnX86, WinIntel_HDRM, XboxOne.

Reports the client device "platform". This can be used by a proxy to implement custom platform-specific behaviour. If this field is missing from a particular info message, please report to Axinom - this means there is a new platform that we don’t yet know about.

Supported since: Widevine API v6.21.0

device_info.supported_license_protocol_versions​

MandatoryData TypePossible Values
YesArray of stringsAny array of strings. For example: ["1", "2"]

Indicates which FairPlay Streaming protocol versions the playback device supports. Note: while some clients are known to indicate support for several versions, the only version publicly documented by Apple, and therefore used by Axinom DRM, is "1".

Supported since: FairPlay API v6.20.0

session_id​

MandatoryData TypePossible Values
NoStringAny string representation of a valid GUID in the 00000000-0000-0000-0000-000000000000 format

The ID of the current playback session. This ID will be constant for all related requests. For example: license renewals (FairPlay, Widevine) and releases (Widevine). This can be used, for example, for session tracking and implementing session-based concurrent playback limiting.

Supported since: Widevine API v6.24.0, FairPlay API v6.20.0

request_type​

MandatoryData TypePossible Values
NoStringOne of: "new", "renewal", "release"

The type of the license request. Knowing this may enable taking advanced action by a license proxy. "new" means this is a request for a new license, with a new session ID. "renewal" means this is a renewal request for an existing license. "release" means this is a request for releasing a persisted license.

Supported since: Widevine API v6.21.0

playback_state​

MandatoryData TypePossible Values
NoString"new_session", "license_renewal_with_valid_content_key_required", "license_renewal_required", "session_stopped"

Indicates the state of the playback when the license request was created. This essentially represents the request type. This is supported on iOS 9+ and modern Safari. * "new_session" - a new playback session has been opened and the device requires a license to start playback. * "license_renewal_with_valid_content_key_required" - device is playing media, but requires a renewed license that contains a valid content key. * "license_renewal_required" - device is playing media, but requires a renewed license (valid content key is not required). * "session_stopped" - playback session is halted due to an error state or a lack of session ID.

Supported since: FairPlay API v6.20.0

streaming_indicator​

MandatoryData TypePossible Values
YesString"requesting_device", "airplay", "av_adapter"

Indicates whether the playback occurs on the requesting device or content is streamed to an external device: * "requesting_device" - playback occurs on the device that sends the license request. * "airplay" - device streams content over AirPlay to Apple TV for playback. * "av_adapter" - device streams content to an Apple digital AV adapter for playback.

Supported since: FairPlay API v6.20.0

license_protocol_version​

MandatoryData TypePossible Values
YesStringAny string. For example: "1".

Indicates the version of the FairPlay Streaming protocol that is used for the current transaction. This is chosen by the playback device as the most recent version that both the playback device and the license service support, where the version supported by the license service is determined by the "KEYFORMATVERSIONS" parameter in the HLS playlist. Note: while some clients are known to indicate support for several versions, the only version publicly documented by Apple, and therefore used by Axinom DRM, is "1".

Supported since: FairPlay API v6.20.0

widevine_cdm_version​

MandatoryData TypePossible Values
NoStringAny string. For example: "4.10.2830.0".

Indicates the CDM version

Supported since: Widevine API v6.26.0

In case of PlayReady and FairPlay, the device ID is always obtainable. However, in case of Widevine, this is not always possible. On some devices and platforms, for example, Google Chrome on desktop devices, Widevine is not able to uniquely identify the device – in such a case, the device_id field is missing in the License Request Info Message. Furthermore, device_id is now deprecated for Widevine. Newer Widevine clients no longer report the device ID. Therefore, use allowed_device_certificate_serial_numbers for Widevine instead.

The recommended way of executing device ID based restrictions is to use Axinom DRM License Service in the Proxy Mode. Proxy Mode is strongly advised to obtain License Request Info. In the Proxy Mode, the device ID based restriction decisions can be made upon receiving the License Request Info Message along with the license response - if device ID in the received License Request Info Message does not match the expected one, the License Proxy may decide not to return the license to the client.

Deprecated Version​

License Request Info Message is used with an Entitlement Message v2 and above. Previously, for the Entitlement Message v1, a data structure called Client Info Message was used.

Revision History​

The table below lists the document versions and any changes to them.

Version

Date

Description

1

April 29, 2019

Initial Revision

2

September 17, 2020

Added device_certificate_serial_number field for Widevine

3

October 14, 2020

Changed the device_certificate_serial_number to a GUID value from a base64 string

4

February 23, 2022

Restructured

5

September 01, 2023
  • Added recommended_client_id, platform, request_type, supported_license_protocol_version, license_protocol_version, playback_state, streaming_indicator, session_id.
  • Added FairPlay and PlayReady-specific examples.

6

April 02, 2024

Replaced "vNext" version information with real versions.

7

February 25, 2025

Added information about how to ensure client tokens persist. Reformatted tables for better readability.