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

Parameter Description
client string Client name
policy object Definition of the policy

See: policy object


policy object

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

Parameter Description Applicable DRM
block_vpn_and_tor boolean Determines if IPs coming from known VPN or tor networks should be blocked

Possible values:
   • true
   • false
ALL
content_id string Content identifier

This is used for tracking content in the stats and is not required.
ALL
duration_lease string End date and time for the license in ISO 8601 (YYYY-MM-DDTHH:MM:SS) format

If both duration_lease and polend are set in a policy then duration_lease will be used.

Also note that duration_lease does not equal the token TTL. The token TTL governs access to the license. License expiry governs access to your media.

The default timezone is Europe/London. However, the timezone can be specified by adding the time offset to the UTC date and time value.

For example:
2021-03-19T14:30:00+01:00
FairPlay
duration_persist string End date and time for the license in ISO 8601 (YYYY-MM-DDTHH:MM:SS) format

If both duration_persist and polend are set in a policy then duration_persist will be used.

Also note that duration_persist does not equal the token TTL. The token TTL governs access to the license. License expiry governs access to your media.

The default timezone is Europe/London. However, the timezone can be specified by adding the time offset to the UTC date and time value.

For example:
2021-03-19T14:30:00+01:00
FairPlay
duration_rental string End date and time for the license in ISO 8601 (YYYY-MM-DDTHH:MM:SS) format

If both duration_rental and polend are set in a policy then duration_rental will be used.

Also note that duration_rental does not equal the token TTL. The token TTL governs access to the license. License expiry governs access to your media.

The default timezone is Europe/London. However, the timezone can be specified by adding the time offset to the UTC date and time value.

For example:
2021-03-19T14:30:00+01:00
FairPlay
geo_whitelist string array List of 3-letter, ISO 3166-1 alpha-3 country codes for all countries that are allowed access

See: Geo Whitelisting
ALL
liccache string Determines if the license should be cached

The implementation depends on the DRM provider.

Possible values:
   • yes
   • no
ALL
match_content_id boolean Determines if the content ID in the token should be compared with the content ID used in the license request

The content ID in the license request will be the same as the content ID used to generate the keys that encrypted a given piece of content.

Possible values:
   • true
   • false

See: Match Content ID
ALL
polbegin string Start date and time for the license in ISO 8601 (YYYY-MM-DDTHH:MM:SS) format

The default timezone is Europe/London. However, the timezone can be specified by adding the time offset to the UTC date and time value.

For example:
2021-03-19T14:30:00+01:00

(FairPlay, Widevine) As long as no other values would cause playback to stop, content will play indefinitely when this and polend have not been set in the policy.
ALL
polend string End date and time for the license in ISO 8601 (YYYY-MM-DDTHH:MM:SS) format


When any of the following parameters are included in a policy with polend, the polend parameter will be overridden:

   • duration_lease
   • duration_persist
   • duration_rental

Also note that polend does not equal the token TTL. The token TTL governs access to the license. License expiry governs access to your media.

The default timezone is Europe/London. However, the timezone can be specified by adding the time offset to the UTC date and time value.

For example:
2021-03-19T14:30:00+01:00

(FairPlay, Widevine) As long as no other values would cause playback to stop, content will play indefinitely when this and polbegin have not been set in the policy.
ALL
securitylevel integer Indicates the minimum Security Level required from a client to allow binding to a license

Possible values:
   • 150 (use only for development)
   • 2000
   • 3000
PlayReady
session object JSON object containing information about a DRM session that can be used to allow or deny a user's license requests

See: policy.session object
ALL
type string Type of license

Possible values:
   • l
   • p
   • r

See: FairPlay
FairPlay


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" }
    }
}
Parameter Description
headers string Any header values required by the API specified in policy.session.url

Example:
"headers":  {"API_KEY": "{api_key}"}
id string Unique ID of the current DRM session
method string API call verb

Possible values:
   • GET
   • POST

When "policy.session.method":"GET", a GET request is made to policy.session.url with a sessionId query string set to policy.session.id.

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

When "policy.method":"POST", a POST request is made to policy.session.url with the headers and a JSON body consisting of the sessionId.

curl -X POST 'https://some-url.com/valid' \
  -H 'API_KEY: {api_key}' \
  -d '{"sessionId": "abcd1234"}'
url string URL of a the specified API



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

Parameter Combination Results
geo_whitelist has been added to the DRM policy
When a license is requested, the geographic location of the client's IP address is checked:

• If the client's IP address is in a country listed in the whitelist, the license request will be successful.

• If the client's IP address is in a country not listed in the whitelist, the request will be denied.

Example:
If the DRM policy is { "geo_whitelist":[ "gbr", "deu" ] }, only users from the UK and Germany will be able to make successful license requests.


Match Content ID

Parameter Combination Results
content_id has been set

AND

"match_content_id":"true"
When a license request is made, the content ID in the license request and the content ID in the Studio DRM token are compared:

• When both content IDs match, a license is served.
• When the content IDs do not match, the license request is denied.
content_id has not been set

OR

"match_content_id":"false"
No content ID comparison is made



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"
}
General Policy Notes
Offline Playback This policy is designed for a subscription business model that allows subscribers to download content that can be watched offline in a mobile application.

The license generated from this policy will not allow playback until polbegin is reached and will expire when polend is reached.
Rental This policy is designed for a rental business model.

The license generated from this policy will expire at the time set by the polend value and will allow immediate playback.
Subscription This policy is designed for a subscription business model.

The license generated from this policy will not allow playback until polbegin is reached and will expire when polend is reached.



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"
}
FairPlay Notes
Lease Specify a lease license by setting "type": "l" in the DRM policy

You can set the expiry of the license using the duration_lease key or the polend key. If both duration_lease and polend are set in a policy, then duration_lease will be used.


Expiration Behavior: After a lease license expires, playback stops. Normally, a player makes a new license request at this point.

Be sure to update the Studio DRM token before the license expiry. Using an expired Studio DRM token will cause the license request to fail.
Persist Specify a persist license (used for offline playback) by setting "type": "p" in the DRM policy

You can set the expiry of the license using the duration_persist key or the polend key. If both duration_persist and polend are set in a policy, then duration_persist will be used.


Setting Considerations:
• When "liccache":"yes" OR "type":"p" is set, a persisted license is generated.
• When "liccache":"no" AND "type":"p" are set, a persisted license is generated.
• When "liccache":"yes" is set, liccache overrides type and a persisted license is generated.

Expiration Behavior: After a persist license expires, playback stops at the license expiry. Additionally, the license is removed from the device.
Rental Specify rental license by setting "type": "r" in the DRM policy

You can set the expiry of the license using the duration_rental key or the polend key. If both duration_rental and polend are set in a policy, then duration_rental will be used.


Expiration Behavior: After a rental license expires, playback continues until the encryption keys change.



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.