---
title: KS Fundamentals
url: https://docs.kaltura.com/docs/getting-started/authentication/ks-fundamentals
---

## 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 |