🔐 Authentication

All three Conversational Agent APIs speak one language for authentication: the Kaltura Session (KS).

Every request must include your KS token in the Authorization header:

Authorization: KS YOUR_KS_TOKEN

That's it! ❤️ No OAuth flows, no token exchanges — just your KS on every call.

Getting a Kaltura Session

A Kaltura Session is a short-lived token that identifies your partner account and user. You generate one using the Kaltura API with your partner ID and admin secret.

Generate a KS token

curl -X POST "https://www.kaltura.com/api_v3/service/session/action/start" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "YOUR_ADMIN_SECRET",
    "userId": "your-user@email.com",
    "type": 2,
    "partnerId": YOUR_PARTNER_ID,
    "expiry": 86400,
    "privileges": "disableentitlement"
  }'

Generate a KS token (JavaScript)

const response = await fetch('https://www.kaltura.com/api_v3/service/session/action/start', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    secret: process.env.KALTURA_ADMIN_SECRET,
    userId: 'your-user@email.com',
    type: 2, // 2 = admin session
    partnerId: YOUR_PARTNER_ID,
    expiry: 86400, // 24 hours
    privileges: 'disableentitlement',
  }),
});

const { ks } = await response.json();
// ks is your token — store it securely!

Using the Token

Include the KS in the Authorization header of every management API request:

Example: List all agents

curl -X POST "https://YOUR_API_HOST/service/agent/action/list" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Example: List all agents (JavaScript)

const response = await fetch('https://YOUR_API_HOST/service/agent/action/list', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

const { objects, totalCount } = await response.json();

Server-side only — never expose your KS in the browser!

Your Kaltura Session is tied to your admin secret and has elevated privileges. Never include it in client-side code, environment variables shipped to the browser, or public repositories.

Always call the management APIs from your backend server. Your server holds the KS; your frontend talks to your backend.

// ❌ BAD — exposing KS in a frontend app
const ks = 'djJ8...your-admin-ks...';
fetch('/service/agent/action/create', { headers: { Authorization: `KS ${ks}` } });

// ✅ GOOD — your backend makes the management API calls
// Frontend → Your Backend → Kaltura Management APIs

Token Expiry

KS tokens expire based on the expiry parameter you set when generating them (in seconds). A common pattern:

• Long-lived backend sessions: 24 hours (expiry: 86400)
• Short-lived user sessions: 1–2 hours

When a token expires, you'll get a 401 Unauthorized response. Re-generate a fresh KS and retry.

Pro tip: Refresh before expiry

Don't wait for a 401 to refresh your token. Build a background refresh that generates a new KS a few minutes before the current one expires. This avoids request failures during token rotation.

Error Responses

Status	Meaning	What to do
401 Unauthorized	Missing or invalid KS token	Check the token is correct and not expired
403 Forbidden	Valid KS but insufficient privileges	Ensure the session has disableentitlement privilege and is an admin session (type 2)

How This Differs from the Control API

If you've used the Control API, its auth flow works differently:

	Management APIs	Control API
Auth method	KS on every request	KS to create session → Bearer token for subsequent calls
Token type	Kaltura Session (KS)	JWT Bearer token
Who calls it	Your backend server	Your backend server (session creation) or client SDK
Scope	Configuration management	Real-time avatar session control

The management APIs are simpler — one KS, all calls. The Control API involves a handoff because it powers real-time streaming that the client SDK consumes directly.

→ Control API Authentication

Next Steps

• 🤖 Agent Service — Create and manage agents
• 🎭 Avatar Service — Configure avatars
• 📦 Catalog Service — Manage catalog items