Create a playback session

Request and consume the DRM-X Universal Playback Session Contract with authentication, trusted Content IDs, and bounded authorization.

View Markdown Live examplesUpdated 2026-10-26

How playback is authorized

Your backend decides who can watch. DRM-X provides playback authorization. The player uses that authorization to request a DRM license.

Viewer
Signs in to your service and requests a video.
Your backend
Checks the user's purchase, subscription, or other permission to watch.
DRM-X
Applies the selected playback rules and returns the playback configuration and authorization.
Player
Uses the returned authorization to request the DRM license needed for playback.

Your backend decides access; DRM-X enforces the signed policy. Encrypted media and DRM licenses follow separate delivery paths.

API

Create a Universal Playback Session#

POST https://api6.drm-x.com/api/v1/playback/environments/{siteId}/sessions
Accept: application/json
Content-Type: application/json
X-DRMX-Client-Id: {siteKey}
X-DRMX-Client-Secret: {accessKey}

{
  "contentId": "course-12-lesson-4",
  "contentType": "vod",
  "drmSystem": "widevine",
  "subject": "customer-user-1001",
  "sessionId": "new-unpredictable-id-per-playback",
  "playbackMode": "streaming",
  "licensePolicyTemplate": "multi-tier-standard",
  "useEnvironmentDefaults": true,
  "applicationId": "customer-web",
  "platformCapabilities": {
    "clientPlatform": "web",
    "drmSystems": ["widevine"],
    "manifestTypes": ["dash"],
    "maximumHeight": 2160,
    "persistentState": false,
    "sdkVersion": "1.2.0-beta.4"
  }
}

A successful Contract v1 response includes the authoritative manifest, available manifest variants, a DRM-specific license URL, a short-lived DRM License Token or customer proxy authorization, a release route, the licensed maximum height, and allowed tracks. Return it with Cache-Control: no-store.

Use one unpredictable session ID for each real playback attempt. Reusing an ID across devices defeats concurrent-stream counting.

Successful response example

This example uses non-working sample URLs and a placeholder token. Read the nested descriptors; compatibility aliases are included for older integrations.

{
  "contractVersion": 1,
  "playbackMode": "streaming",
  "sessionId": "c9006ed8-58c8-45db-9ed0-311d1047c210",
  "contentId": "course-12-lesson-4",
  "drmSystem": "widevine",
  "manifestUrl": "https://media.example.test/course-12/manifest.mpd",
  "manifestUrls": {"dash": "https://media.example.test/course-12/manifest.mpd"},
  "expiresAt": "2026-10-26T12:10:00Z",
  "drm": {
    "system": "widevine",
    "licenseServerUrl": "https://license6.drm-x.com/v1/licenses/widevine",
    "drmLicenseToken": "REDACTED_EXAMPLE_ONLY",
    "tokenType": "Bearer",
    "fairPlayCertificateUrl": null
  },
  "release": {
    "url": "https://license6.drm-x.com/v1/playback-sessions/release",
    "method": "POST",
    "authorizationScheme": "Bearer"
  },
  "policy": {"maximumHeight": 1080, "allowedTrackTypes": ["AUDIO", "SD", "HD"]},
  "tracks": {"audioLanguageSelection": true, "subtitleLanguageSelection": true, "languageTagStandard": "BCP-47"},
  "platformCapabilities": null,
  "playerBranding": null,
  "token": "REDACTED_EXAMPLE_ONLY",
  "tokenType": "Bearer",
  "licenseServerUrl": "https://license6.drm-x.com/v1/licenses/widevine",
  "fairPlayCertificateUrl": null,
  "releaseUrl": "https://license6.drm-x.com/v1/playback-sessions/release",
  "maximumHeight": 1080,
  "allowedTrackTypes": ["AUDIO", "SD", "HD"]
}

Authentication and trusted request fields#

Call this API from your backend with a project API client that has license-tokens:create. Use the environment UUID as siteId. Your authenticated viewer calls your endpoint; your endpoint supplies the trusted fields below.

Field	Meaning	Integration rule
`contentId`	The published content reference	Resolve from your trusted catalog after the entitlement check.
`subject`	Your stable viewer identifier	Derive from the authenticated session, not a client-supplied user ID.
`drmSystem`	`widevine`, `playready`, `fairplay`, or `wiseplay`	Match the selected DRM to the player capabilities.
`sessionId`	Identity of this playback attempt	Generate a fresh unpredictable value for each attempt.
`contentType`	`vod` or `live`	Use the type registered for the content.
`playbackMode`	`streaming` in Contract v1	Offline playback requires a later contract extension.
`licensePolicyTemplate` / `licensePolicy`	A named policy or custom policy	Select on your server; do not supply both. See policy rules.
`platformCapabilities`	Platform, DRM systems, manifest types, and device hints	Send explicit capabilities with new integrations. They describe the client; they do not override license policy.

Consume the response descriptors#

Use the nested Contract v1 descriptors. Do not construct license URLs from guesses or replace registered manifest URLs with player inputs.

Response field	How to use it
`contractVersion`	Verify that the returned contract version is supported by your integration.
`manifestUrl` / `manifestUrls`	Load the authoritative selected manifest or a returned compatible variant.
`expiresAt`	The expiry of this bounded authorization.
`drm`	Read `system`, `licenseServerUrl`, `drmLicenseToken`, `tokenType`, and the optional `fairPlayCertificateUrl`. A customer token proxy can replace the browser-facing authorization with its own bounded session.
`release`	Use its `url`, `method`, and `authorizationScheme` to release the session when playback ends.
`policy`	Honor `maximumHeight` and `allowedTrackTypes`. The provider still enforces the signed policy.
`tracks`	Read audio/subtitle language-selection capability and the language-tag standard.

Return your player response with Cache-Control: no-store. Never forward the project Access Key to the browser. Restrict authorization headers to the returned license and certificate routes.

Handle errors and release reservations#

Inspect the HTTP status and machine-readable code. Retain the requestId for troubleshooting and respect retryable; a denied entitlement or invalid policy needs a corrected decision, not a retry loop. See the playback session error reference.

Release the reservation on Stop, playback replacement, terminal errors, and application shutdown. A fresh playback attempt gets a new session ID.

POST https://license6.drm-x.com/v1/playback-sessions/release
Authorization: Bearer REDACTED_EXAMPLE_ONLY
Accept: application/json

HTTP/1.1 200 OK
{"contractVersion":1,"released":true,"code":"license_session_released","requestId":"example-request-id"}

Use the returned release URL and authorization scheme, with the same DRM License Token. No request body is required. An authenticated repeat release returns HTTP 200 with released false and code license_session_not_active. Expired or invalid authorization can fail before release; obtain fresh authorization for a new playback attempt. Retry temporary service failures with bounded backoff.

This public contract describes streaming. Customer-owned offline endpoints and device-bound persistent licenses have separate workflows; do not reuse this streaming response as an offline license.