Studio DRM Token API v2

Create a Studio DRM token.


The Studio DRM token has several purposes:

  • Authentication: 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.
  • Delivering the DRM policy to the license server: The playback rights of a user for individual pieces of content can be set dynamically. A single user may be granted different rights on a single piece of content depending on business requirements.
  • Signed authorization: Authorization is signed 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.

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. Then, the Studio DRM token should be delivered to the client side for use by a player in a license request.

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

🚧

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



Studio DRM token structure

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

  • Client name
  • Token generation time in ISO 8601 (yyyy-MM-ddThh:mm:ss) format
  • Token version
  • Encrypted DRM policy
  • Signed hash
300300

Studio DRM Token v2 diagram

🚧

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.



Generate a Studio DRM token

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

Request

curl -X POST https://token.vudrm.tech/v2/generate \
     -H 'x-api-key: {api_key}' \
     -d '{"clientName": "<client>","policy": {"content_id":"<content-id>","rental_duration_seconds":"<duration>","offline":false}}'

Body Parameters

Parameters Description
clientName 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.

Parameters Description
can_renew boolean Defines if the license can be renewed

Possible values:
   • true
   • false
client_data object List of key-value pairs that enables providing additional information

The client_data parameter can be used to generate custom license statistics reports. If you wish to take advantage of this please contract [JW Player Support](https://support.jwplayer.com/submit-support-case).
content_id string Content identifier

This is used in conjunction with match_content_id to lock a Studio DRM token to a single content ID and for tracking content in the stats. It is not a required parameter.
fairplay object Policy settings for FairPlay

See: policy.fairplay object
firstplayback_seconds integer Once playback is initiated, the duration in seconds of time within which a user must complete playback

Once the window completes, the license expires.

The firstplayback_seconds parameter cannot be used when offline is set to false.
geo_restrictions object Geo restriction settings for the policy

See: policy.geo_restrictions
match_content_id boolean Determines if the content ID in the token should be compared with the content ID used in the license request

Possible values:
   • true
   • false
offline boolean Defines if the the license can be cached for offline playback

Possible values:
   • true
   • false
playready object Policy settings for PlayReady

See: policy.playready object
rental_duration_seconds integer Duration in which the license is valid
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
widevine object Policy settings for Widevine

See: policy.widevine object

policy.fairplay

The values of this object override values in the general section of the policy and apply only to FairPlay.

{
    "fairplay" : {
        "rental_duration_seconds":2700,
        "license_type":"r"
    }
}
Parameters Description
firstplayback_seconds integer Once playback is initiated, the duration in seconds within which a user must complete playback

The value of this parameter is used with the license_type is set to p.

The firstplayback_seconds parameter cannot be used when offline is set to false.

Expiration Behavior: After a persist license expires, playback stops at the license expiry.
license_duration_seconds integer Duration in seconds in which the license is valid

The value of this parameter is used when the license_type is set to l.

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.
license_type string Type of license

Possible values:
   • l: Lease
   • p: Persistent license
   • r: Rental license
rental_duration_seconds integer Duration in seconds in which the license is valid before it is used

The value of this parameter is used when the license_type is set to r.

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

policy.geo_restrictions

{
    "geo_restrictions": {
        "metro_code_whitelist":[501],
        "country_code_whitelist":["usa"],
        "block_vpn_and_tor":true
    }
}
Parameters Description
block_vpn_and_tor boolean Determines if IPs coming from known VPN or tor networks should be blocked

Possible values:
   • false
   • true
country_code_whitelist string array List of 3-letter, ISO 3166-1 alpha-3 country codes for all countries that are allowed access

The geographical location of the viewer's IP is checked against the list of country codes. If the viewer's country code is not in the list, the request will be denied.
metro_code_whitelist integer array List of geographic location metro codes that are allowed access

The geographical location of the viewer's IP is checked against the list of metro codes. If the viewer's metro code is not in the list, the request will be denied.

policy.playready

The values of this object override values in the general section of the policy and apply only to PlayReady.

Parameters Description
begin_datetime string Start date and time for the license in ISO 8601 (YYYY-MM-DDTHH:MM:SS) format

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

Also note that end_datetime does not equal the token TTL. Token TTL governs access to license. License expiry governs access to content.

For example:
2021-03-19T14:30:00+01:00
firstplayback_seconds integer Once playback is initiated, the duration in seconds within which a user must complete playback

The firstplayback_seconds parameter cannot be used when offline is set to false.

Expiration Behavior: After a persist license expires, playback stops at the license expiry. Additionally, the license is removed from the device.
security_level 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

policy.session

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.

{
    "session": {
        "id": "someID",
        "url": "https://www.some-url.com/valid",
        "method": "GET",
        "headers": { "myHeader": "someValue", "myOtherHeader": "someOtherValue" }
    }
}
Parameters Description
headers stringAny header values required by the API specified in url

Example:
"headers": {"API_KEY": "{api_key}"}
id stringUnique ID of the current DRM session
method stringAPI call verb

Possible values:
   • GET
   • POST

When "policy.method":"GET", a GET request is made to url with a sessionId query string set to id.
GET https://some-url.com/valid?sessionId=abc123 

When "policy.method":"POST", a POST request is made to policy.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 the specified API

policy.widevine

The values of this object override values in the general section of the policy and apply only to Widevine.

📘

To automatically renew online Widevine licenses, can_renew must be set to true and rental_duration_seconds must be set for a duration greater than 1800 seconds.

With "can_renew": true, Widevine attempts to renew the license every 1800 seconds. Setting the rental_duration_seconds to greater than 1800 seconds prevents any license gaps.

Parameters Description
firstplayback_seconds integer Once playback is initiated, the duration in seconds within which a user must complete playback

The firstplayback_seconds parameter cannot be used when offline is set to false.
rental_duration_seconds integer Duration in seconds in which the license is valid before it is used

Once playback has started, this value is no longer enforced.

Expiration Behavior: After a rental license expires, playback continues until the encryption keys change.
license_duration_seconds integer Duration in seconds in which the license is valid

Expiration Behavior: After the license expires, playback stops.

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.

Additional policy Object Considerations

The following table explains several parameter combinations to consider when creating a policy.

Parameter Combinition Result
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