Skip to main content

License Acquisition API

License Acquisition API is the frontend-facing API for the License Requests. Typically, the requests are made by a video player.

The API is exposed by the License Service.

The same API is exposed by each DRM-specific implementation (Widevine, FairPlay, PlayReady). It is up to the frontend/player to decide which DRM to use and to direct the respective license request to the correct endpoint. For example, a request originating from a Chrome browser will have to use the Widevine License Service endpoint, and a request originating from a Safari browser will have to use the FairPlay License Service endpoint.

Endpoints​

License Acquisition API provides a single endpoint: POST /AcquireLicense.

License Request​

The HTTP POST request’s body shall contain a license request generated by a CDM (Content Decryption Module) which is used by a DRM-capable player. The license request data structure is encrypted and can only be understood by the License Service. The player application merely plays the role of a messenger between the CDM and the License Service. The player cannot read or tamper with the contents of license requests or responses. The DRM License returned by the License Service can only be used on the same device from which the License Request was initiated.

Even if the details about the license request data structure are not published by the vendors of the DRM technologies, it is known that the license request contains:

  • Key ID - ID of the Content Key needed to decrypt the video (Player knows the Key ID from the video metadata)
  • Device Identification - Device ID and other information (DRM technology-specific)
  • IP Address - IP Address of the client device.

Authorization​

The License Acquisition API doesn’t require HTTP-level Authorization (Authorization header is not used).

However, for the License Service to grant the license, the license request shall carry an Axinom DRM License Service Message with a valid Entitlement Message inside. An Axinom DRM License Service Message shall be added to the request in exactly one of the following ways:

  • HTTP header X-AxDRM-Message
  • HTTP query string parameter AxDrmMessage
  • The Custom Data part of a PlayReady License Request (PlayReady only).
https://drm-widevine-licensing.axprod.net/AcquireLicense?AxDrmMessage=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.
eyJ2ZXJzaW9uIjoxLCJjb21fa2V5X2lkIjoiNjllNTQwODgtZTllMC00NTMwLThjMWEtMWViNmRjZDBkMTRl
iwiZXhwaXJhdGlvbl9kYXRlIjoiMjAyMC0wMS0wMSIsIm1lc3NhZ2UiOnsidmVyc2lvbiI6MiwidHlwZSI6I
VudGl0bGVtZW50X21lc3NhZ2UiLCJjb250ZW50X2tleXNfc291cmNlIjp7ImlubGluZSI6W3siaWQiOiIyMT
hYzFkYy1jOGEyLTQ1NzUtYmFmNy1mYTRiYTU2YzM4YWMifV19fX0.
LbK1pATJaFJFnPhs-IiuEdj7IVsZaBIv3kwYwQgw0-U

All popular video players in use today allow to use one of the three options above. If your project-specific situation does not allow any of the above options, consider using the Proxy Mode.

License Service recognizes the DRM tenant based on the used com-key-id.

License Response​

A successful response contains a DRM License. This license can be used by the video player (strictly speaking: by the CDM) on the device from which the request originated.

If the return_license_request_info field in the Entitlement Message was set to true, a custom HTTP header X-AxDRM-Message will contain a Axinom DRM License Service Message with a License Request Info Message inside. Read Device Specific Restriction to understand how this License Request Info Message can be used.

Interactions between a Player and the License Service​

Interactions between a player and the License Service

Errors​

In case of an error, the service returns an HTTP status code following HTTP conventions.

Additionally, the service adds a human-readable explanation of the error in a custom HTTP header X-AxDRM-ErrorMessage.

If HTTP/1 is used the same error explanation is returned as HTTP ReasonPhrase.

Caution

We recommend that you rely on the X-AxDRM-ErrorMessage header because the ReasonPhrase is not supported by HTTP/2, and also some HTTP/1 client libraries do not support parsing the ReasonPhrase.

CORS clients, such as browsers, sometimes don’t have access to custom HTTP headers. To enable such clients reading the informational headers, service adds Access-Control-Expose-Headers header to the response and explicitly enables reading of the "X-AxDrm-ErrorMessage" header.

Troubleshooting​

If your request fails, you can see the error details from My Mosaic / Errors.

While it is not possible to manually create a valid license request, it is possible to intercept a real request made by a player, record it and reuse for your own development/debug/troubleshooting purposes (to avoid the need to actually start playback of a video every time you want to test the License Service response to a specific request with an Entitlement Message you generated).

If you would like to analyse the content of a license request, you can use Axinom’s License Request Decoder Tool (see https://tools.axinom.com).