REST API reference

Authentication

All /api/v1/* endpoints require a Bearer token in the Authorization header.

Authorization: Bearer kvch_live_<your_api_key>

Embed JWT

The embed player at /embed/{videoId} requires a signed JWT passed as ?t=. Sign it on your backend — never in the browser.

Algorithm & Secret

Algorithm: HS256. Secret: your API key plaintext (e.g. kvch_live_...).

JWT Payload

{
  "vid":          "vid_abc123",          // required — must match the video in the URL
  "viewer_id":    "user_42",             // required — your internal user ID
  "viewer_email": "[email protected]", // optional — shown in watermark
  "viewer_phone": "+919876543210",       // optional — shown in watermark
  "iat":          1716000000,            // issued-at (unix seconds)
  "exp":          1716007200             // expiry   (unix seconds) — max 24h recommended
}

iframe embed

<iframe
  src="https://videokavach.com/embed/vid_abc123?t=<jwt>&autoplay=1"
  width="720" height="405"
  allowfullscreen
  frameborder="0"
></iframe>

PHP example (WordPress plugin / Moodle)

<?php
function kavach_sign_token(string $videoId, $viewer): string {
    $apiKey = KAVACH_API_KEY; // your API key
    $header  = rtrim(strtr(base64_encode(json_encode(['alg'=>'HS256','typ'=>'JWT'])), '+/', '-_'), '=');
    $payload = rtrim(strtr(base64_encode(json_encode([
        'vid'          => $videoId,
        'viewer_id'    => (string) $viewer->ID,
        'viewer_email' => $viewer->user_email,
        'iat'          => time(),
        'exp'          => time() + 7200,
    ])), '+/', '-_'), '=');
    $sig = rtrim(strtr(base64_encode(hash_hmac('sha256', "$header.$payload", $apiKey, true)), '+/', '-_'), '=');
    return "$header.$payload.$sig";
}

Branding Override

By default the player shows the logo and accent colour configured in your account's Settings → Player Branding. You can override these per-embed by including a branding field in the JWT payload.

JWT payload with branding override

{
  "vid":          "vid_abc123",
  "viewer_id":    "user_42",
  "viewer_email": "[email protected]",
  "iat":          1716000000,
  "exp":          1716007200,

  "branding": {
    "logoUrl":      "https://your-cdn.com/tenant-logo.png",
    "logoPosition": "top-right",   // top-left | top-right | bottom-left | bottom-right
    "logoSize":     "small",       // small | medium | large
    "logoOpacity":  80,            // 0–100
    "accentColor":  "#4f46e5"
  }
}

All branding fields are optional

Remove logo for a specific embed

"branding": { "logoUrl": null }

Videos

List videos — example response

GET /api/v1/videos

{
  "videos": [
    {
      "id": "vid_abc123",
      "title": "Module 1 — Introduction",
      "status": "ready",
      "durationSec": 1842,
      "width": 1920,
      "height": 1080,
      "sourceBytes": 524288000,
      "createdAt": "2026-05-01T10:00:00Z"
    }
  ]
}

Automated Domain Management

Platforms that license content to multiple organisations typically need to add a licensee's domain to every video in a course when a subscription activates, and remove it on expiry or revocation.

Pattern — add domain on license activation

async function addLicenseeDomain(kavachBaseUrl, kavachApiKey, videoId, newDomain) {
  const res = await fetch(`${kavachBaseUrl}/api/v1/videos/${videoId}/domains`, {
    headers: { Authorization: `Bearer ${kavachApiKey}` },
  });
  const { effective } = await res.json();
  const updated = [...new Set([...effective, newDomain])];
  await fetch(`${kavachBaseUrl}/api/v1/videos/${videoId}/domains`, {
    method:  "PUT",
    headers: { Authorization: `Bearer ${kavachApiKey}`, "Content-Type": "application/json" },
    body:    JSON.stringify({ domains: updated }),
  });
}

Domain pattern formats

Captions & Audio Tracks

Account Settings

Webhooks

VideoKavach sends an HTTP POST to your webhook URL when video processing completes or fails. Configure your webhook URL in Settings or via PUT /api/v1/settings/webhook.

Request headers

X-Kavach-Event:     video.ready
X-Kavach-Signature: <hmac-sha256-hex>
Content-Type:       application/json

Signature verification

// Node.js
import { createHmac, timingSafeEqual } from "crypto";

function verifyKavachSignature(body: string, sig: string, apiKey: string): boolean {
  const expected = createHmac("sha256", apiKey).update(body).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

video.ready payload

{
  "event": "video.ready",
  "video": {
    "id":           "vid_abc123",
    "title":        "Module 1 — Introduction",
    "duration_sec": 1842,
    "variants": [
      { "label": "360p",  "height": 360,  "bandwidth_bps": 896000 },
      { "label": "720p",  "height": 720,  "bandwidth_bps": 2928000 },
      { "label": "1080p", "height": 1080, "bandwidth_bps": 5192000 }
    ]
  }
}

Analytics

The same watch data the dashboard shows, for pulling into your own reporting. Both endpoints are read-only.

Devices

Used by native apps that support offline download. Devices are counted per (tenant, viewer_id) pair, so a student who buys from two different institutes gets a separate device budget from each.

Errors

All errors return JSON with error and message fields.

{
  "error":   "storage_quota_exceeded",
  "message": "Storage quota exceeded for your plan"
}