Skip navigation

Authorization Backend: Video Access Control by Your System's Rules

Kinescope lets you control access to videos and live streams through an external authorization backend. This means you decide who can watch a specific video — based on your system’s rules (courses, subscriptions, roles, etc.).

Who this article is for

  • LMS developers — need to control video access by course and lesson
  • Subscription platform owners — need to restrict access based on subscription status
  • Corporate system administrators — need to configure access by role and group
  • Backend developers — need to integrate an access control system with Kinescope

When you need an authorization backend

Here are typical situations where this is useful:

  • Access to part of the media library: a user purchased a course or package but doesn’t have access to the entire library.
  • Subscription: videos are only accessible while the subscription is active (or the trial period hasn’t expired).
  • Individual lesson purchases: access only to specific videos the user paid for.
  • Corporate access: access by organizational role (employees, partners) or group membership.
  • Contextual restrictions: access by IP (IPv4, accurate to a /24 subnet), geolocation, time window, device, or session.

If at least one of these scenarios applies to you — read on. Below is how to set up access checking in two steps.

How access checking works (4 steps)

  1. You pass a user identifier to the Kinescope player.
  2. When a user starts playing a video or a live stream, Kinescope asks your backend: “Can this user watch this?”
  3. Your backend checks the rules (course, subscription, role, etc.) and responds: 200 (allow) or 403 (deny).
  4. The player opens or blocks access.

Now let’s walk through how to set this up.

Setup: step 1 — passing a user identifier

When embedding the player on a website, pass the authorization token via the drmauthtoken parameter in the URL:

<iframe
  src="https://kinescope.io/embed/pcFNnQGsD59CMKte2SQQaz?drmauthtoken=${user_id}"
  width="640"
  height="360"
  frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture; encrypted-media;"
></iframe>

You can use any string as a token: user_id, a JWT token, or another identifier your backend can verify. The drmauthtoken value reaches your backend unchanged, in the token field. If the parameter isn’t passed, token contains an empty string.

Recommendation (security): For production, we recommend using a signed JWT in drmauthtoken. This protects against token substitution on the client. On the backend, validate the JWT signature and extract the user_id.

For developers: When validating a JWT, check the standard fields: exp (expiration), aud (audience), iss (issuer) — this improves security.

Setup: step 2 — connecting your backend

For Kinescope to be able to call your backend to check access, add your endpoint’s URL to the project or workspace settings via the Kinescope API.

Important: The API token in the Authorization: Bearer header must be in UUID format. You can get a token from the Kinescope Dashboard in Settings → API tokens. Learn more about authorization and error handling in the general API guidelines.

DRM can be configured at two levels:

  • Workspace — applies to all projects
  • Project — applies to a specific project (overrides workspace settings)

To check access, Kinescope uses the settings of the project that contains the video or live stream. If the project has no settings, the workspace settings apply.

Setting up the authorization backend URL via API:

For the entire workspace:

curl -X PUT "https://api.kinescope.io/v1/drm/auth" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/drm/authorize",
    "username": "drm_user",
    "password": "drm_password",
    "strict": false
}'

For a specific project:

curl -X PUT "https://api.kinescope.io/v1/drm/auth/${PROJECT_ID}" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/drm/authorize",
    "username": "drm_user",
    "password": "drm_password",
    "strict": false
}'

Request parameters:

  • url (required) — URL of your access check endpoint (where Kinescope will send requests during playback)
  • username (optional) — username for Basic Auth to your service. If a username is set, Kinescope sends the username and password in the Authorization: Basic header. If not, the request goes out without this header
  • password (optional) — password for Basic Auth
  • strict (optional) — strict mode. true — viewing is allowed only after a 200 response. false — only a 403 response denies viewing; errors and an unavailable backend don’t stop playback. See Strict and non-strict mode

Checking current settings:

# For workspace
curl -X GET "https://api.kinescope.io/v1/drm/auth" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}"

# For project
curl -X GET "https://api.kinescope.io/v1/drm/auth/${PROJECT_ID}" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}"

All settings methods are described in the API reference.

Important: Kinescope sends a POST request with JSON to your URL (request format). Access is decided by the HTTP response code: 200 to allow, 403 to deny. The response body is ignored.

What arrives at your backend

Kinescope sends a POST request to your authorization URL every time the player requests a license for playback:

  • at playback start — 1–2 requests;
  • on key rotation during a live broadcast;
  • when the player requests the license again.

Responses aren’t cached, and a request isn’t retried after a timeout or an error: one attempt per license request. Plan your backend load by the number of license requests, not the number of viewers.

Example request:

POST /drm/authorize HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Basic ZHJtX3VzZXI6ZHJtX3Bhc3N3b3Jk

{
  "id": "7127f2d7-0e96-40d0-9a03-2e987c096466",
  "ip": "11.22.33.0",
  "type": "vod",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
}

Headers:

  • Content-Type: application/json — the request body is JSON
  • Authorization: Basic … — the username and password (username, password) from the authorization settings. The header is present only if a username is set

Request body fields:

FieldTypeContents
idstring (UUID)The video ID or the event id being accessed. For live streams, see Live streams and their recordings
typestringvod — a video, including a live stream recording; live — a live broadcast
tokenstringThe value of the drmauthtoken parameter from the embed URL, unchanged (e.g., user_id or JWT). The field is always present: if the parameter isn’t passed, it’s an empty string
ipstringThe viewer’s IPv4 address with a /24 subnet mask, e.g., 11.22.33.0. IPv6 isn’t supported: if the viewer has an IPv6 address, don’t rely on this field
user_agentstringThe viewer’s User-Agent

The request has no video_id field: the video ID or the event id arrives in the id field.

If your access rules must also work for viewers with IPv6, base them on the token, id, and user_agent fields rather than ip.

Live streams and their recordings

For a live broadcast, the request is sent only for live streams with encryption enabled — with the protected: true parameter (Create event). Requests during a broadcast and for a recording differ:

What the viewer watchestypeid
Live broadcastliveThe event id from the Live API (Get event). For a recurring event, it’s constant. It isn’t stream.id, which changes from broadcast to broadcast
Recording after the broadcastvodID of the recording video. It matches video_id from the live.finished webhook and the video id from Event videos

Example request during a broadcast:

{
  "id": "0d5e8f8a-4b7c-4e61-9a3f-2c1b7d9e6a54",
  "ip": "11.22.33.0",
  "type": "live",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
}

A recurring event has several recordings — one per broadcast. If a broadcast wasn’t recorded, video_id in the live.finished webhook is a nil UUID.

Access to the broadcast and to the recordings is granted separately. Map access to the broadcast by the event id, and access to recordings by each recording’s video ID. If a recording is saved to another project, it’s checked against that project’s authorization settings: a broadcast and its recording may be checked against different settings.

What to return in response

Kinescope decides based on the HTTP response code alone; the response body is ignored. Kinescope waits 5 seconds for a response in both modes. If viewing is allowed, Kinescope issues the decryption key and the player starts playback. What happens with each response depends on the strict parameter:

Your backend’s responsestrict: truestrict: false
200 OKViewing allowedViewing allowed
403 ForbiddenViewing deniedViewing denied
Any other code (401, 404, 5xx, etc.)Viewing deniedViewing allowed
No response within 5 seconds or backend unavailableViewing deniedViewing allowed

Strict and non-strict mode

  • Strict (strict: true) — viewing is allowed only if your backend responds with 200. Any other code or no response within 5 seconds means denial.
  • Non-strict (strict: false) — only a 403 response denies viewing. Other codes, no response within 5 seconds, and an unavailable backend don’t stop playback.

For developers: To reliably deny viewing, return exactly 403 — in non-strict mode, 401, 404, and 5xx allow viewing.

How to check access (minimal scheme)

Here’s what you need to do in your authorization handler:

  1. Extract user_id from token: if you use JWT — validate the signature and extract user_id; if you pass user_id directly — just use it.
  2. Identify what the user is watching: by id and type, determine which course/package/section the video or live stream belongs to.
  3. Check permissions in your system: does the user have access (purchase, subscription, role, group, etc.).
  4. Return a response: 200 if access is granted, otherwise 403.

Briefly in pseudocode:

user_id = verify_and_extract_user_id(token)
if user_id is empty -> 403

if user_has_access(user_id, id, type) -> 200
else -> 403

Example: access only to a purchased course

Say your site has courses and a user bought only one of them. How do you check access to a video in that course?

Step 1: Map Kinescope content to courses in your system (e.g., a course_videos table with course_id and kinescope_id fields). If a course includes live streams, add the event id — Create event and Get event return it — and the recording video ID of each broadcast: the live.finished webhook sends it in the video_id field.

Step 2: In your authorization handler:

  • Extract user_id from token (validate JWT if you use it).
  • Find course_id by the id from the request.
  • Verify the user is enrolled in the course, has paid, and the course is active.
  • Return 200 if all checks pass, otherwise 403.

Pseudocode:

course_id = find_course_by_kinescope_id(id)
if course_id is empty -> 403

if enrollment_is_active(user_id, course_id) -> 200
else -> 403

How it works (in detail)

Here’s what happens when a user watches a video:

  1. User opens the page — your site passes the authorization token (e.g., user_id or JWT) to the Kinescope player via the drmauthtoken parameter.
  2. The player requests a license — at playback start, not when the page opens. Kinescope sends your backend a POST request with JSON containing:
    • the authorization token (the one you passed in drmauthtoken);
    • the content ID and type: a video (vod) or a live broadcast (live);
    • the user’s IP address (IPv4 with a /24 mask) and User-Agent.
  3. Your backend checks access — reviews the rules in your system (course, subscription, role, etc.) and returns a response:
    • HTTP 200 — access granted, the license server issues a decryption key, video becomes available.
    • HTTP 403 — access denied, video does not play.
    • Any other code or no response within 5 seconds — the result depends on strict mode.
  4. The player receives the response — opens or blocks video access.

Done! Now you can control video access using any rules from your system.

What’s next?

After setting up the authorization backend, we recommend:

  1. DRM file encryption — additional content protection
  2. Video access restrictions — other ways to restrict access
  3. General API guidelines — authorization and request format

Still have questions? Write to the support chat within the Kinescope interface — our specialists will help!