REST API Recipes - Authentication

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)

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.

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).

AppTokens → Privileged KS with appToken.startSession

High level flow:

1. 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.
2. Get a base KS (e.g., widget session).
3. Compute tokenHash = HASH( baseKS + token ) with the same hash type as the app token.
4. 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.