KS Fundamentals - Authentication

KS Fundamentals

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:

1. Signature check — Verify the SHA-1 signature matches the decrypted payload
2. Expiry check — Reject if the KS has expired (Unix timestamp comparison)
3. Action limit — If actionslimit:N is set, decrement and reject if exhausted
4. Revocation check — Check if session.end was called for this KS or its sessionid group
5. Permission check — Verify the KS type and role grant access to the requested service/action
6. Entitlement check — If entitlements are enabled, verify the user has category membership for the requested content
7. Account check — Verify the partner ID is active and the service is enabled
8. 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