Authentication & Services

← Back to the API Reference index

Authentication

Every call requires a Kaltura Session (KS) token in the Authorization header.

Mint an admin KS:

KS=$(curl -s -X POST "https://www.kaltura.com/api_v3/service/session/action/start" \
  -d "format=1" \
  -d "secret=$AGENTIC_ADMIN_SECRET" \
  -d "partnerId=$AGENTIC_PARTNER_ID" \
  -d "type=2" \
  -d "expiry=86400" \
  -d "privileges=disableentitlement" | tr -d '"')

Pass it on every call: Authorization: KS <token>

Mint an Agent KS — scopes the token to a single agent (agentid:<agentId>) instead of a whole intellect config. Entitlement stays on; userId isn't supported (use Conversation or Admin for that):

import { Management } from '@kaltura/intelligent-agents/management';

const mgmt = new Management({ partnerId, adminSecret });
const agentToken = await mgmt.sessions.createAgentToken({ agentId: '1_abc123' });

Raw wire equivalent:

AGENT_KS=$(curl -s -X POST "https://www.kaltura.com/api_v3/service/session/action/start" \
  -d "format=1" -d "secret=$AGENTIC_ADMIN_SECRET" -d "partnerId=$AGENTIC_PARTNER_ID" \
  -d "type=2" -d "expiry=1800" \
  -d "privileges=agentid:1_abc123" | tr -d '"')

Keep disableentitlement server-side, for management/admin operations only. A real KS's privileges are encrypted and unreadable client-side, so the SDK can't detect or stop a disableentitlement KS from being handed to a conversation/end-user session. Nothing will warn you if you do this by mistake. See Security & Compliance and Kaltura's own KS/privilege reference.

Bind a session to a real end-user identity (userId). By default every minted KS is anonymous. The reserved {{ sys__user_id }} template variable (see § Converse) resolves to an empty string in every prompt/converse call unless you bind a real identity.

Pass userId to bind the KS to a real end-user id instead. The value flows straight through to session/start's own userId field, per-call only, never cached. This makes sys__user_id resolve server-side and lets converse-side memory/analytics attribute the turn to a real user:

import { Management } from '@kaltura/intelligent-agents/management';

const mgmt = new Management({ partnerId, adminSecret });

// Any conversation/admin token can carry a real user identity.
const conv = await mgmt.sessions.createConversationToken({ configId, userId: 'learner-123' });
const reply = await mgmt.converseOnce(configId, 'What have we covered so far?', {}, conv);

Raw wire equivalent:

CONV_KS=$(curl -s -X POST "https://www.kaltura.com/api_v3/service/session/action/start" \
  -d "format=1" -d "secret=$AGENTIC_ADMIN_SECRET" -d "partnerId=$AGENTIC_PARTNER_ID" \
  -d "userId=learner-123" -d "type=2" -d "expiry=1800" \
  -d "privileges=geniegpcid:1389" | tr -d '"')

userId is optional on both createAdminToken() and createConversationToken() — omit it and behavior is unchanged (anonymous, exactly as before).

The Five Services

An agent is built from five services that layer on top of each other. All calls use POST with JSON (GET /assistant/status is the one exception).

Once deployed, the conversation surface (/assistant/converse, /v1/thread/, /mcp/) lives on genie.nvp1.ovp.kaltura.com. Utility endpoints (/application/) for widget resolution and runtime init are on api.avatar.us.kaltura.ai.

To embed a live avatar in a browser, go to Widget & Runtime Init or jump straight to UC-12 Anonymous End-User Embed.