Callback Authorization

How Callback Authorization works

Core concept

When a user triggers a license request, DRMtoday must receive a Customer Rights Token (CRT) that defines whether playback is allowed and under what conditions. Without this authorization, no license is issued.

With Callback Authorization (mode value CALLBACK), the player sends a license request directly to DRMtoday with identifying context in the x-dt-custom-data header. DRMtoday then calls your backend at the configured callback URL, asks whether the user is authorized, and expects an HTTP 200 response containing the CRT. Only after your backend approves does DRMtoday issue the DRM license.

Unlike Token Authorization, the CRT is not pre-embedded in a JWT — it is determined at license-request time by your server.

Operational workflow

1. Request DRM license — The player sends a license request to DRMtoday with x-dt-custom-data (see Sending custom data).
2. Authorization callback — DRMtoday POSTs to your callback URL with asset and session details from the request.
3. Validate session — Your backend validates the sessionId and confirms the user is authorized (membership, subscription, rental status, etc.).
4. Determine CRT — Your backend builds the Customer Rights Token for this user, asset, and session.
5. Respond HTTP 200 — Your backend returns the CRT as JSON in the response body.
6. Issue DRM license — DRMtoday receives the CRT and delivers the license to the player.

Sending custom data in license requests

In Callback mode the player does not carry a pre-signed JWT. Instead, it sends a Base64-encoded JSON object in the license request header so DRMtoday can forward the context to your callback endpoint.

1. Build the custom data object

The player (via your application / browser) attaches these fields:

{
  "userId": "rental1",
  "merchant": "46c7d6fb-f299-4501-a474-0aedc26ea0a2",
  "sessionId": "p0"
}

• userId — Your identifier for the viewer (arbitrary string you define).
• merchant — Organization / Merchant ID on DRMtoday (ORGANIZATION_ID).
• sessionId — Session identifier your backend can validate during the callback.

2. Encode and attach to the license request

Base64-encode the JSON and send it as a license header:

x-dt-custom-data: eyJ1c2VySWQiOiJyZW50YWwxIiwibWVyY2hhbnQiOiIuLi4iLCJzZXNzaW9uSWQiOiJwMCJ9

In JavaScript (as used by the VideoJS demo):

licenseHeaders: {
  "x-dt-custom-data": btoa(JSON.stringify({
    userId: form.drmUserId,
    merchant: form.drmMerchant,
    sessionId: form.drmSessionId
  }))
}

The assetId is typically passed in the license server URL (e.g. ?assetId=CPIX-test for Widevine), not inside x-dt-custom-data.

3. Your backend validates on callback

When DRMtoday POSTs to your callback URL, use the session and asset information in the request body to look up the user, verify entitlements, and return the appropriate CRT. The player never receives the CRT directly — only DRMtoday does.

Security guarantees

Callback Authorization shifts the authorization decision to a server-to-server call that the client cannot bypass:

In summary: the player provides identity context (userId, sessionId, merchant), DRMtoday acts as the broker, and your backend is the authorization authority that decides whether and how content may be played. See also Token Authorization for the alternative upfront-token model.

Comparison with Token Authorization

Configure the callback endpoint

Before enabling Callback Authorization, prepare a publicly reachable HTTPS endpoint that DRMtoday can POST to, and define the CRT JSON your handler will return.

Define the CRT profile

The CRT describes playback rights DRMtoday should encode into the license. Use the Set CRT page in this demo to view or edit the CRT JSON stored on the server.

Example CRT profile:

{
  "profile": {
    "type": "rental",
    "relativeExpiration": "P7D",
    "playDuration": "PT10H"
  }
}

In production, your callback handler should build the CRT dynamically based on the asset, user, and session received in the callback request — not return a static file for every user.

Implement the authorization callback

Your callback endpoint must accept POST requests from DRMtoday, validate the session, and respond with HTTP 200 OK and CRT JSON in the body.

In this demo environment, the callback is implemented at:

callbacks/drmtoday-auth-callback.php

Minimum handler responsibilities:

1. Parse the JSON body DRMtoday sends (asset ID, session ID, user context).
2. Validate that the sessionId is active and the user is entitled to watch.
3. Build or load the CRT for the requested asset.
4. Return HTTP 200 with the CRT as JSON (use adapter JSON_V1 unless DRMtoday specifies otherwise).

Enable Callback Authorization

Register your callback URL and switch the organization's license delivery mode to Callback authorization (CALLBACK). You can do this through the CastLab GUI or via the DRMtoday REST API.

After enabling Callback Authorization:

• Players send x-dt-custom-data instead of x-dt-auth-token.
• DRMtoday POSTs to your callback URL on each license request.
• No shared secret is required for signing JWTs (unlike Token Authorization).

Using the CastLab GUI

The CastLab GUI is the DRMtoday web dashboard used to manage organizations and license delivery authorization.

Step 1 — Sign in and select your organization

1. Open the DRMtoday dashboard:
   • Staging: https://fe.staging.drmtoday.com
   • Production: https://fe.drmtoday.com
2. Log in and click Switch on your organization.

Step 2 — Open License Delivery Authorization

1. In the left sidebar, click License delivery authorization.
2. Open the Authorization tab.

Step 3 — Register callback URL and save

1. Under Default settings, select Callback authorization (step 2 in the screenshot above).
2. Set Callback version to JSON POST request V1 and enter your publicly reachable Callback URL (e.g. https://your-server/callbacks/drmtoday-auth-callback.php) (step 3).
3. Click Save changes (step 4).

You can also use the Test your callback tab in the same screen to verify DRMtoday can reach your endpoint.

Via the DRMtoday REST API

Switch the organization to CALLBACK programmatically using the DRMtoday CAS protocol (same flow as Token Authorization — see Token Authorization API steps for CAS login details).

Prerequisites

• DRMtoday API credentials — username and password for CAS login.
• Organization ID — your merchant UUID.
• Callback URL — public HTTPS endpoint that returns CRT JSON.

Settings endpoint:

{FRONTEND_BASE_URL}/frontend/rest/config/v1/{ORGANIZATION_ID}/auth/settings

curl -i -X POST "https://auth.staging.drmtoday.com/cas/v1/tickets" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=YOUR_USERNAME" \
  --data-urlencode "password=YOUR_PASSWORD"

{
  "mode": "CALLBACK",
  "callbackUrl": "https://your-server.example.com/callbacks/drmtoday-auth-callback.php",
  "callbackAdapterId": "JSON_V1"
}

curl -X POST "${SETTINGS_URL}?ticket=${SERVICE_TICKET}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "mode": "CALLBACK",
    "callbackUrl": "https://your-server.example.com/callbacks/drmtoday-auth-callback.php",
    "callbackAdapterId": "JSON_V1"
  }'

API notes

• Service tickets are single-use — obtain a new one for each operation.
• TGT URLs expire — repeat CAS login if Step 2 fails.
• Ensure your callback endpoint is live before switching players to Callback mode.

Verify the setup

After configuration, confirm that Callback Authorization is active and the player sends x-dt-custom-data on license requests.

Test on the VideoJS Demo

1. Open the VideoJS Demo and enable Enable DRM.
2. The License delivery authorization panel should show CALLBACK as the current active method (use Switch to CALLBACK if needed).
3. Fill in User ID, Session ID, Merchant, and Asset ID, then click Load Video.

Confirm drmConfig headers

In the Player Options panel, verify that drmConfig includes licenseHeaders with x-dt-custom-data — a Base64-encoded JSON object containing userId, merchant, and sessionId.

"licenseHeaders": {
  "x-dt-custom-data": "eyJ1c2VySWQiOiJyZW50YWwxIiwibWVyY2hhbnQiOiIuLi4iLCJzZXNzaW9uSWQiOiJwMCJ9"
}