Studio DRM Token API v1 (Standalone)

🚧

Use the Studio DRM Token API v2 to generate your tokens. The Studio DRM Token API v1 is temporarily maintained for legacy implementations.

Benefits of the v2 of the Studio DRM Token API include:

• The updated encryption and hashing algorithms makes it more secure than v1
• The redesigned policy structure in the token allows for easier policy creation
• More robust, scalable, and faster than v1

For information on migrating to v2, see the migration section below.

Migration to Studio DRM Token API v2

To migrate to v2 of the Studio DRM Token API, simply start using the Studio DRM Token API v2 for all new requests. Because the tokens are dynamically generated for each content request from the client, over time there will cease to be any v1 tokens in use.

No changes need to be made in your client-side players for the DRM license request. It is only necessary to use v2 tokens instead of v1.

Contact JW Player Support if you need assistance defining your Studio DRM policy with the v2 Token API.

Overview

The Studio DRM token has two purposes: authentication and the delivery of the DRM policy to the license server. It also represents a signed authorization on the client's behalf for JW Player to issue a DRM license to the holder of the token, issuing a Studio DRM token to a player will grant that player access to the DRM-protected content.

Due to the first purpose, Studio DRM tokens have a limited lifetime and are designed to be single use. Please contact JW Player Support if you do not know what the Studio DRM token's TTL is for your account.

The second purpose allows the user's playback rights for individual pieces of content to be set dynamically. A single user may be granted different rights on a single piece of content depending on business requirements.

Studio DRM tokens should be generated using the Studio DRM token API. The request to the Studio DRM token API should be made from a server side application and the Studio DRM token should then be delivered to the client side for use by a player in a license request.

All requests made to this API will require your API key set as the header API-KEY. If you do not know or have not been given your API key please contact JW Player Support.

🚧

IMPORTANT

Studio DRM tokens must not be generated on the client side.

Studio DRM token structure

test-client|2018-26-11T11:01:04Z|cO9H1B2VKw0WyyNTOfoHEw==|05aff2dd06f4c52291b7a032c815ce8f599cf409

The Studio DRM token is comprised of four components each separated by the pipe character (ASCII code 124):

• Client name
• Time the token was generated in an ISO 8601 (yyyy-MM-ddThh:mm:ss) format
• Encrypted DRM policy
• Signed hash

🚧

Studio DRM tokens are designed to be single use and have a one-to-one relationship with the license request. Each license request must use a new Studio DRM token.

Studio DRM tokens expire with a TTL set to around 30 seconds. The time a token will expire is calculated by the time the token is generated plus the TTL. The time a token was generated is displayed in the token. This is a separate time to the DRM policy times set in the encrypted DRM policy.

Studio DRM token API

Generate a Studio DRM token

https://token.vudrm.tech/generate
Generates a Studio DRM token

Request

curl -X POST https://token.vudrm.tech/generate \
     -H 'API_KEY: {api_key}' \
     -d '{"client": "{client}","policy": {"content_id":"{content-id}","polend":"{pol-end}","liccache":"no"}}'

Body Parameters

policy object

This table is not an exhaustive list. If you require the use of more advanced settings, please contact JW Player Support.

policy.session object

You can set information about the current DRM session in the policy used by the Studio DRM token. Using the current DRM session information, JW Player makes a request to an API of your choosing.

If the API returns a 200 status, a valid license will be served back. Otherwise, no license will be returned.

{
    "polbegin": "02-04-2019 12:00:00",
    "polend": "02-04-2019 17:00:00",
    "session": {
        "id": "someID",
        "url": "https://www.some-url.com/valid",
        "method": "GET",
        "headers": { "myHeader": "someValue", "myOtherHeader": "someOtherValue" }
    }
}

"headers":  {"API_KEY": "{api_key}"}

curl GET 'https://some-url.com/valid?sessionId=abc123'

curl -X POST 'https://some-url.com/valid' \
  -H 'API_KEY: {api_key}' \
  -d '{"sessionId": "abcd1234"}'

Additional policy Object Considerations

There are limitations depending on environments that are not explained in the table. Please refer to the following tables for more detail.

Geo Whitelisting

Match Content ID

DRM Policy Examples

General DRM policy examples

There are three types of DRM policies that can be applied to all DRM providers: rental, subscription, and offline playback license.

{
    "content_id":"filename",
    "polend":"DD-MM-YYYY HH:mm:ss",
    "liccache":"yes"
}

{
    "content_id":"filename",
    "polend":"DD-MM-YYYY HH:mm:ss",
    "type":"r"
}

{
    "content_id":"filename",
    "polbegin":"DD-MM-YYYY HH:mm:ss",
    "polend":"DD-MM-YYYY HH:mm:ss",
    "type":"l"
}

Default DRM Policy Creation

👍

If you wish to utilize this feature please contact JW Player Support.

You can specify a default DRM policy that will be used when JW Player receives a Studio DRM token.

If you want all requested licenses to default to caching the license, the default DRM policy would be the following.

{ 
  "liccache":"yes" 
}

With this default policy set, a Studio DRM token with a policy that included { "polend":"DD-MM-YYYY HH:mm:ss" } would be updated to the following.

{ 
  "liccache":"yes", 
  "polend":"DD-MM-YYYY HH:mm:ss"
}

Once a default policy is set, the values in the default policy can be overridden by adding new values in the policy passed in the Studio DRM token.

To override a default DRM policy – { "liccache":"yes" } – so that a license would not be cached, the following policy should be in the Studio DRM token.

{ 
  "liccache":"no" 
}

Any of the values in the policy object can be set in the default DRM policy.

DRM-specific Policies

FairPlay

{
    "polbegin": "01-01-0001 00:00:00",
    "polend": "12-31-9999 23:59:59",
    "liccache": "yes",
    "firstplayback": 10675199,
    "securitylevel": 2000,
    "match_content_id": false
}

FairPlay has three types of license: lease, persist, and rental.

FairPlay licenses can only be persisted past the user session by an offline enabled iOS application. When using Safari a session will be preserved until the browser tab is closed.

FairPlay does not allow playback over non-HDCP connections.

{
    "content_id":"filename",
    "duration_lease":"DD-MM-YYYY HH:mm:ss",
    "polend":"DD-MM-YYYY HH:mm:ss",
    "type":"l"
}

{
    "content_id":"filename",
    "duration_persist":"DD-MM-YYYY HH:mm:ss",
    "polend":"DD-MM-YYYY HH:mm:ss",
    "type":"p"
}

{
    "content_id":"filename",
    "duration_rental":"DD-MM-YYYY HH:mm:ss",
    "polend":"DD-MM-YYYY HH:mm:ss",
    "type":"r"
}

PlayReady

{
    "polbegin": "01-01-0001 00:00:00",
    "polend": "12-31-9999 23:59:59",
    "liccache": "yes",
    "firstplayback": 10675199,
    "securitylevel": 2000,
    "match_content_id": false
}

PlayReady has an extensive list of policy options. The majority of these options are supported via the Studio DRM token's policy. Please contact JW Player Support for more details.

Widevine

{
    "polbegin": "02-04-2019 12:00:00",
    "polend": "02-04-2019 17:00:00",
    "liccache": "no",
    "match_content_id": false
}

Widevine licenses can only be persisted past the user session by an Android application. When using Chrome, a session will be preserved until the browser tab is closed.