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 examples ↗Updated 2026-09-05

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.1.0-preview.13"
  }
}

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.

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.