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

Kinescope lets you control video access 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, 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 tries to watch a video, Kinescope asks your backend: “Can this user watch this video?”
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.

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)

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
• password (optional) — password for Basic Auth
• strict (optional) — strict checking 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}"

Important: Kinescope sends an HTTP request with JSON to your URL (see example below). In response, simply return 200 (allow) or 403 (deny).

What arrives at your backend

When a user tries to watch a video, Kinescope sends JSON with context to your authorization URL:

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

Field descriptions:

• id — ID of the video being accessed
• token — authorization token you passed in drmauthtoken (e.g., user_id or JWT)
• ip — user’s IP address
• type — content type (usually "video")
• user_agent — user’s browser User-Agent

What to return in response

Your backend must return one of these HTTP codes:

For developers: If your backend is temporarily unavailable (5xx), Kinescope won’t be able to check access. We recommend setting up monitoring and quick service recovery.

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 the video context: by id (video ID), determine which course/package/section the video 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_to_video(user_id, video_id) -> 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 videos to courses in your system (e.g., a course_videos table with course_id and video_id fields).

Step 2: In your authorization handler:

• Extract user_id from token (validate JWT if you use it).
• Find course_id by video_id.
• 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_video(video_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 opens a page with the player:

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. Kinescope calls your backend — sends an HTTP request with JSON containing:
   • the authorization token (the one you passed in drmauthtoken);
   • the video ID;
   • the user’s IP address 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.
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!