Kaltura Session (KS) Generation and Management¶

Generate, use, and rotate Kaltura Sessions (KS) — the signed, time-limited tokens that authenticate every Kaltura API call and player embed.

Base URL: https://www.kaltura.com/api_v3 (may differ by region/deployment)
Auth: KS passed as ks parameter in POST form data, or as embed URL parameter
Format: Form-encoded POST, format=1 for JSON responses

1. When to Use¶

Every Kaltura API integration starts here -- a valid Kaltura Session (KS) is required for every API call and player embed across the platform.
Backend automation systems generate server-side sessions with appropriate type, expiry, and privileges to control what each integration can access.
Client-facing applications use AppToken-based session exchange to obtain scoped KS tokens without exposing admin secrets to end users.
Security and compliance teams define session privilege policies that enforce content isolation, user tracking, and access boundaries.

2. Prerequisites¶

Partner ID: Your Kaltura account identifier, available from the KMC under Settings > Integration Settings.
Admin secret (for session.start): Required for server-side KS generation. Keep strictly server-side and never embed in client code.
Service URL: Set $KALTURA_SERVICE_URL to your account's regional endpoint (default: https://www.kaltura.com/api_v3).
Understanding of session types: USER (type=0) for end-user contexts, ADMIN (type=2) for backend administration. This guide covers both.

3. What is a KS and when to use which flow¶

A Kaltura Session (KS) is a signed, time-limited token you attach to API calls and player embeds. KS can be USER (type=0) or ADMIN (type=2). Use USER for almost everything where an end-user is interacting with apps or data; use ADMIN only for trusted backend-only workflows with short TTLs and strict configurations (roles, privileges).

Common use-cases and considerations:

Server-to-server or trusted backend: session.start → returns a KS with the privileges and expiry you request. Run this server-side only to keep secrets secure.
App-to-API with elevated but scoped permissions: use Application Tokens and appToken.startSession. You obtain a basic (unprivileged) KS, compute a hash with the app token, and exchange it for a privileged KS — keeping admin secrets and hashing strictly server-side.
Widget/player bootstrap (the player will generate this KS by itself if no KS was provided to the player: session.startWidgetSession to get a base KS used in the App Token flow.

KS Internal Structure¶

A KS is a base64-encoded string containing these components:

Field	Description
Partner ID	The Kaltura account that issued the KS
User ID	The user identity bound to this session
Type	0 = USER, 2 = ADMIN
Expiry	Unix timestamp when the KS becomes invalid
Privileges	Comma-separated privilege strings (e.g., `sview:*,privacycontext:PORTAL`)
Random number	Prevents replay of identical requests
KS data	Additional session context (action limits, session ID)
Signature	SHA-1 hash of all fields above — tamper-proofing

KS v2 (current default) wraps the payload in AES-CBC encryption before base64 encoding, so the internal fields are not readable by inspecting the string. The server decrypts and validates on every request.

KS Validation Flow¶

The server validates the KS on every API request in this sequence:

Signature check — Verify the SHA-1 signature matches the decrypted payload
Expiry check — Reject if the KS has expired (Unix timestamp comparison)
Action limit — If actionslimit:N is set, decrement and reject if exhausted
Revocation check — Check if session.end was called for this KS or its sessionid group
Permission check — Verify the KS type and role grant access to the requested service/action
Entitlement check — If entitlements are enabled, verify the user has category membership for the requested content
Account check — Verify the partner ID is active and the service is enabled
Set user context — Bind the validated userId to the request for ownership, analytics, and audit

If any step fails, the server returns a KalturaAPIException with the relevant error code (INVALID_KS, EXPIRED_KS, SERVICE_FORBIDDEN, etc.).

KS Creation Methods — Comparison¶

Method	Credentials Required	Best For	Trade-offs
`session.start`	partnerId + adminSecret	Backend tools, server-side automation	HTTP roundtrip; exposes admin secret (keep server-side only)
`session.startWidgetSession`	partnerId only (no secret)	Anonymous player bootstrap, AppToken base KS	Unprivileged — read-only access to public content
`appToken.startSession`	appToken ID + HMAC hash	Production integrations, client-facing apps	Preferred: no secrets exposed, revocable, scoped privileges
`user.loginByLoginId`	email + password	End-user self-authentication, mobile apps	User-managed credentials; requires user provisioning first

4. Common security practices¶

Least privilege: Prefer USER KS; scope permissions to what the call needs.
Short TTLs: Set per the expected user interaction duration, balancing security with renewal frequency.
Backend only: Keep admin secrets and app token secrets on the server side.
Entitlements over broad privileges: Enforce access via Access Control/Entitlements and privacy context strings in KS. Use specific privileges; use * only for controlled internal ADMIN sessions.
Rotate Application Tokens and Sessions regularly. Revoke as needed using session.end.
API secrets are permanent. The adminSecret and secret for a Kaltura account cannot be regenerated, rotated, or revoked. If a secret is compromised, contact Kaltura support. This is the primary reason to use Application Tokens (AppTokens) instead of embedding secrets — AppTokens can be revoked and reissued independently. See AppTokens Guide.

5. REST API Recipes¶

All calls use the v3 endpoint with form-encoded POST data and format=1 for JSON responses.

Base URL: https://www.kaltura.com/api_v3/ (this URL can change depending on geo region, or deployment, the account was configured on)

5.1. Generate a KS (backend) with session.start¶

curl -X POST "$KALTURA_SERVICE_URL/service/session/action/start" \
  -d "partnerId=$KALTURA_PARTNER_ID" \
  -d "secret=$KALTURA_ADMIN_SECRET" \
  -d "userId=testUser" \
  -d "type=0" \
  -d "expiry=1800" \
  -d "privileges=sview:*" \
  -d "format=1"

Parameter	Type	Required	Description
`secret`	string	Yes	Admin secret (`type=2`) or user secret (`type=0`)
`partnerId`	integer	Yes	Your Kaltura partner ID
`type`	integer	Yes	`0` = USER, `2` = ADMIN
`userId`	string	No	User ID for the session (default: empty)
`expiry`	integer	No	TTL in seconds (default: 86400 = 24 hours)
`privileges`	string	No	Comma-separated privilege strings (e.g., `sview:,edit:`)

Response: The KS string (with format=1, wrapped as "djJ8OTc2NDYx...").

"djJ8OTc2NDYx..."

type=0 is USER, type=2 is ADMIN.
expiry is in seconds (1800 = 30 minutes).

When to use: server-side APIs, signed/secure player embeds, upload/edit tasks that your backend coordinates. Scope privileges to the minimum required for each session.

5.2. Bootstrap a base KS with session.startWidgetSession¶

curl -X POST "$KALTURA_SERVICE_URL/service/session/action/startWidgetSession" \
  -d "widgetId=_$KALTURA_PARTNER_ID" \
  -d "format=1"

widgetId is _<partnerId> (underscore prefix).
The response JSON contains { "result": { "ks": "<WIDGET_KS_STRING>", ... } }.

This will be used as initial session for AppTokens, or for non-authenticated light sessions such as anonymous player embeds (generated by the player itself when a KS is not provided).

5.3. AppTokens → Privileged KS with appToken.startSession¶

High level flow:

Create & store an Application Token (this action is performed once by the account admin to provide API access to a 3rd party trusted-scope partner. This step basically provisions an application security scope). See the AppTokens Guide for full details.
Get a base KS (e.g., widget session).
Compute tokenHash = HASH( baseKS + token ) with the same hash type as the app token.
Call appToken.startSession(tokenId, tokenHash, ...) to receive the privileged KS.

Keep the token and hashing strictly server-side. sessionPrivileges and sessionUserId are locked at token creation and enforced on every session minted from the token. Configure them at creation time.

Step 1 -- Get a widget (base) KS:

curl -X POST "$KALTURA_SERVICE_URL/service/session/action/startWidgetSession" \
  -d "widgetId=_$KALTURA_PARTNER_ID" \
  -d "format=1"

Save the returned result.ks value as WIDGET_KS.

Step 2 -- Compute the token hash:

Compute tokenHash = SHA256(WIDGET_KS + APP_TOKEN_VALUE) using your language's crypto library. The hash algorithm must match what was set when the Application Token was created (SHA256 is recommended).

For example, in a shell:

TOKEN_HASH=$(echo -n "${WIDGET_KS}${KALTURA_APP_TOKEN}" | shasum -a 256 | awk '{print $1}')

Step 3 -- Exchange for a privileged KS:

curl -X POST "$KALTURA_SERVICE_URL/service/apptoken/action/startSession" \
  -d "ks=$WIDGET_KS" \
  -d "id=$KALTURA_APP_TOKEN_ID" \
  -d "tokenHash=$TOKEN_HASH" \
  -d "userId=testUser" \
  -d "type=0" \
  -d "expiry=1800" \
  -d "sessionPrivileges=sview:*" \
  -d "format=1"

The response JSON contains the privileged KS in result.

You can disable or delete tokens (appToken.update → status, or appToken.delete) immediately revoking the app’s ability to mint KS.

6. Passing the KS to APIs and the Player¶

APIs: include ks= in form data for each call.
Player embeds: pass ks in the player setup or in the iframe embed URL.

7. Privileges: what to actually use¶

Keep it tight:

Playback: sview:* (+ enforce entitlements and access control profiles in your account configuration).
Upload/edit tools: add only what’s required for the desired feature set (e.g., edit specific objects or rely on server APIs that hold ADMIN).
Use privacy context (e.g., privacycontext:EDU_PORTAL) in KS to align with entitlement rules rather than over-permitting the session, and to ensure the session is restricted according to user and content scope.
Reserve * for short-lived backend ADMIN sessions that stay server-side.

8. Renewal, caching, and fallback¶

TTL you control: you set expiry when starting the session; store issued_at + expiry in your app and refresh as needed before it lapses.
Client pattern: your frontend should get KS rendered from your backend. The network never sees secrets.
Always pass KS in POST so it is never cached in proxies.
The Kaltura API validates the KS on every request automatically and returns an error if it is invalid or expired. Validation is implicit — use any API call to confirm a KS is valid.
Store KS in memory only; set cache headers to prevent caching.
Pass KS in POST bodies or PlayKit provider config, keeping it out of URLs where it could appear in referrers, logs, and proxies.
Revoke a session immediately with session.end:

curl -X POST "$KALTURA_SERVICE_URL/service/session/action/end" \
  -d "ks=$KALTURA_KS" \
  -d "format=1"

After session.end, the KS is immediately rejected by all subsequent API calls. Use this for logout flows, session revocation, and security incident response.

9. Error Handling¶

Common KS-related error codes: INVALID_KS (malformed, expired, or revoked), MISSING_KS (no KS provided), SERVICE_FORBIDDEN (KS lacks permission), EXPIRED_KS (session past TTL), ACTION_BLOCKED (action limit reached).
On invalid/expired KS or insufficient privileges: re-issue with correct scope.
On 5xx / transient: use exponential backoff (e.g., 500ms, 1s, 2s, jitter), and cap retries. Monitor your request rate to stay within throttling limits.
Observability: log who asked for a session, requested TTL & privileges, and the call outcome (success/failure). Keep secrets out of logs and KS masked (leave last 6 chars).

Retry strategy: For transient errors (HTTP 5xx, timeouts), retry with exponential backoff: 1s, 2s, 4s, with jitter, up to 3 retries. For client errors (4xx, INVALID_KS, insufficient privileges), fix the request before retrying — these will not resolve on their own.

10. Entitlements & KS Privileges Patterns¶

10.1. Make the client KS playback-only¶

Lock KS to a minimal playback role: add setrole:PLAYBACK_BASE_ROLE so only a white-listed set of read/player calls is allowed (e.g., baseEntry.get, flavorAsset.list).

If your content is public and unauthenticated, you can use a Widget KS instead (anonymous, READ-only, for publicly available assets). For protected content, issue a USER KS with entitlements (see below).

10.2. Enforce entitlements with privacy context¶

If your catalog uses Entitlements, enable server-side checks on the KS and set the privacy context that scopes what the user can see: * enableentitlement — tells Kaltura to enforce entitlement checks on this KS. * privacycontext:<LABEL> — sets the entitlement partition ( is free-text label you define in the KMC per category).

Example: enableentitlement,privacycontext:PORTAL_A ensures results are scoped to the category membership of privacy context PORTAL_A. Use enableentitlement on all client-facing KS.

10.3. Scope what can be viewed or listed¶

Playback scope: Allow all playback in the entitlement context: sview:*. Or lock to a single entry: sview:<ENTRY_ID> (use with KS-restricted access control to ensure entries are set to never allow anonymous access).
Listing across owners: list:* enables listing entries beyond the session's current user. Use only when your UX requires global search/browse.

10.4. Identify the user when you can¶

If your app requires authentication, set userId when you issue the KS. This ties server behavior and visibility to that user (e.g., lists are constrained for USER KS; ownership and visibility derive from the user in the KS, analytics are tied to the session' userId).

10.4.1 Analytics tracking¶

Specifying an app id (privilege: appId:<APP_NAME-APP_DOMAIN>) which contains the name and domain of the app allows you to get specific analytics per application, for cases where you’re running your application across various domains.

10.5. Extra hardening knobs (use sparingly)¶

Add one or two of these when risk justifies it:

Action budget: actionslimit:<N> — cap how many API calls the KS can make.
IP lock: iprestrict:<IPv4> — restrict KS use to a single IP.
URI lock: urirestrict:/api_v3/* — restrict which API paths the KS can call.

All three reduce blast radius if a KS leaks. NOTE: IP restriction should be set up alongside a delivery profile that enforces CDN IP Tokenization. If this is needed, reach out to your Kaltura Specialist for account setup.

10.6. App-specific scoping (generic pattern)¶

Some applications read app-specific hints from the KS to route or filter queries (for example, an application ID or category constraints). Keep these server-parsed and namespaced to avoid collisions: For example: genieid:<AI_GENIE_INSTANCE>, etc. These can be read and used by the app and Kaltura backend in various contexts.

Kaltura platform enforces only its known privileges; your app can parse and honor the custom ones as needed.

10.7. Copy/paste privilege sets¶

Authenticated playback (entitlements on): setrole:PLAYBACK_BASE_ROLE,enableentitlement,privacycontext:PORTAL_A,sview:*
Single-item playback ticket: setrole:PLAYBACK_BASE_ROLE,enableentitlement,privacycontext:PORTAL_A,sview:1_abcd1234,actionslimit:4
Hardened client KS (adds IP & URI restrictions): setrole:PLAYBACK_BASE_ROLE,enableentitlement,privacycontext:PORTAL_A,sview:*,iprestrict:203.0.113.7,urirestrict:/api_v3/*

(All examples assume a USER KS issued server-side and delivered to the client via POST, not URL.)

Use scoped privileges; reserve disableentitlement and broad write access for controlled backend ADMIN sessions. Issue ADMIN sessions server-side with short TTLs, and call session.end to revoke when done.

10.8. Bulk logout / revocation via sessionid privilege¶

Set sessionid:<GUID> on the KS privileges and keep that GUID on your backend. If you ever need to kill a whole cohort of sessions (e.g., logout user from all devices), call session.end on a KS that has the same sessionid:<GUID> and reissue sessions with a new GUID.

sessionid privilege essentially groups a set of KS’s together. When session.end is called with a ks that has sessionid=X, all other KS’s that have sessionid=X become invalid as well.

11. Best Practices¶

Use AppTokens in production. Generate KS via appToken.startSession with HMAC — keep admin secrets off application servers (see AppTokens Guide).
Use USER KS (type=0) for client-side operations. Reserve ADMIN KS (type=2) for server-side workflows that require write access.
Set short TTLs. 1 hour for user-facing sessions, 15 minutes for server-side automation. Shorter sessions reduce exposure if a token leaks.
Scope privileges minimally. Use setrole, privacycontext, sview, and iprestrict to limit what a KS can access.
Call session.end to revoke when done. Use the sessionid privilege to enable bulk logout across devices.
Pass KS in POST bodies, not URLs. URL parameters appear in referrer headers, proxy logs, and browser history.

Mobile / Client-Side KS Best Practices¶

Mobile and single-page apps require special care because compiled binaries and client-side JavaScript are accessible to end users:

Keep adminSecret on your backend server only. API secrets are permanent — use Application Tokens (AppTokens) for any scenario requiring revocable credentials. See AppTokens Guide.
Generate KS server-side and pass to the client per-session. Issue fresh KS tokens per session to ensure continuous access. Tokens embedded in compiled binaries can be extracted by end users.
Three recommended strategies for client-side KS:
Anonymous access — Use session.startWidgetSession for public, unauthenticated content (player bootstrap, public galleries).
Server-generated KS — Your backend generates a scoped USER KS (via session.start or appToken.startSession) and passes it to the client per-session. The client never sees secrets.
User login — Use user.loginByLoginId for apps where users authenticate with their own credentials. The KS is generated server-side and returned to the client.

Special Partner IDs¶

Certain partner IDs are reserved by the Kaltura platform for internal purposes:

Partner ID	Purpose
-1	Batch Manager (internal job processing)
-2	Admin Console
-3	Hosted Pages
0	Shared/global resources
99	Default template partner

These IDs appear in logs and system metadata. Customer accounts always have positive partner IDs.

API Getting Started — API structure, first call, multirequest batching, error handling
AppTokens API — Secure server-to-server auth without sharing admin secrets (HMAC-based KS generation)
Upload & Delivery — Upload content and construct playback URLs (requires KS)
eSearch — Search entries, categories, users (requires KS)
Player Embed — Embed the player with KS for access-controlled content
REACH — Enrichment services marketplace: captions, translation, moderation, AI analysis, and more (requires KS)
Agents Manager — Automate workflows with triggers and actions (Bearer KS)
AI Genie — Conversational AI and RAG search over video content (KS auth)
Events Platform — Virtual events with Bearer KS auth
Multi-Stream — Dual/multi-screen entries (requires KS)
App Registry — Register application instances (Bearer KS)
User Profile — Per-app user profiles and attendance (Bearer KS)
Messaging — Template-based email messaging (Bearer KS)
Webhooks — Event-driven HTTP callbacks and email notifications (requires KS)
User Management API — Provision users and assign roles before creating sessions
Categories & Access Control API — Category entitlements and access control profiles (related to disableentitlement / enableentitlement KS privileges)
Analytics Reports — appId privilege tags analytics per-application
Custom Metadata — KS required for metadata profile management
Distribution — Admin KS required for distribution profile management
Multi-Account Management — session.impersonate for cross-account operations
Experience Components — KS passed to embedded components via config
Gamification — KS authentication for gamification microservice