---
title: Entitlement System
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/categories-entitlement-system
---

## Entitlement System


Entitlement is Kaltura's mechanism for restricting content visibility based on category membership. It combines category privacy settings, user membership, and KS privileges.

### How Entitlement Works

Content entitlements govern which users can see which entries. Entitlements are configured at the category level by setting a **privacy context** (`privacyContext` field) -- a free-text label (English characters, no commas or spaces) that identifies the application context.

Applications such as Content Hubs use entitlements to implement "authenticated content channels."

1. **Category privacy** (`privacy` field) sets the baseline visibility rule.  
2. **Category membership** (`categoryUser`) determines which users have access to `MEMBERS_ONLY` categories.  
3. **KS privileges** control whether entitlement is enforced and which privacy contexts are applied.  
4. **Content owner** always has access to their own content regardless of category settings.  

### KS Privileges for Entitlement

| Privilege | Description |
|-----------|-------------|
| `enableentitlement` | Activates entitlement enforcement for this session |
| `privacycontext:LABEL` | Sets the privacy context to match against category `privacyContext` values |
| `disableentitlement` | Explicitly disables entitlement (default for ADMIN KS) |
| `disableentitlementforentry:ENTRY_ID` | Bypasses entitlement for a specific entry |

Generate a USER KS with entitlement:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/session/action/start" \
  -d "format=1" \
  -d "partnerId=$KALTURA_PARTNER_ID" \
  -d "secret=$KALTURA_ADMIN_SECRET" \
  -d "type=0" \
  -d "userId=jane.doe@example.com" \
  -d "privileges=enableentitlement,privacycontext:myapp"
```


### Entitlement Enforcement Decision Flow

The server evaluates content access in this order (first match wins):

| Step | Check | Result if True |
|------|-------|----------------|
| 1 | Entitlement disabled for this entry by widget/feed services | **ALLOWED** |
| 2 | Account's `defaultEntitlementEnforcement` is FALSE | **ALLOWED** |
| 3 | KS has `disableentitlement` OR `disableentitlementforentry` matching this entry | **ALLOWED** |
| 4 | KS `userId` is the entry owner | **ALLOWED** |
| 5 | KS `userId` has edit or publish permission on the entry | **ALLOWED** |
| 6 | Entry is NOT associated with any categories | **ALLOWED** |
| 7 | ALL of the entry's categories have `privacyContext = null` | **ALLOWED** |
| 8 | KS `privacycontext` matches one of the entry's categories' `privacyContext` AND `category.privacy` is ALL (1) | **ALLOWED** |
| 9 | KS `privacycontext` matches AND `category.privacy` is AUTHENTICATED_USERS (2) AND KS has valid `userId` | **ALLOWED** |
| 10 | KS `privacycontext` matches AND `category.privacy` is MEMBERS_ONLY (3) AND `userId` is a category member | **ALLOWED** |
| 11 | None of the above conditions met | **DENIED** |

### Content Visibility with Multiple Categories

When an entry is assigned to multiple categories, the **least restrictive** privacy setting determines access. If an entry is in both a `MEMBERS_ONLY` category and an `ALL` category within the same privacy context, the entry is accessible to everyone.

### Privacy Context Configuration

Privacy context is a free-text label that ties categories to applications:

- Assign the same `privacyContext` to an entire category branch to scope entitlement per application  
- Use `privacyContexts` (plural) for multiple comma-separated labels when a category serves multiple applications  
- The KS `privacycontext` privilege must match the category's `privacyContext` for entitlement to be evaluated  
- Categories without a `privacyContext` are not subject to entitlement enforcement  

### Account-Level Entitlement Configuration

The `defaultEntitlementEnforcement` property on `KalturaPartner` controls global enforcement:

- **true (default):** Entitlement is enforced. API calls must provide a KS with the correct `privacycontext` and a `userId` who is a member of the category.  
- **false:** Entitlement is not enforced by default. Any valid KS can access content. The application is responsible for implementing its own entitlement logic.

### Setting Up Entitlement -- Complete Walkthrough

1. Create a category with `privacy=3` (MEMBERS_ONLY) and a `privacyContext`:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/category/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "category[objectType]=KalturaCategory" \
  -d "category[name]=Premium Content" \
  -d "category[privacy]=3" \
  -d "category[privacyContext]=myapp"
```


2. Add users as members of the category:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/categoryUser/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "categoryUser[objectType]=KalturaCategoryUser" \
  -d "categoryUser[categoryId]=$CATEGORY_ID" \
  -d "categoryUser[userId]=jane.doe@example.com" \
  -d "categoryUser[permissionLevel]=3"
```


3. Assign entries to the category:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/categoryEntry/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "categoryEntry[objectType]=KalturaCategoryEntry" \
  -d "categoryEntry[categoryId]=$CATEGORY_ID" \
  -d "categoryEntry[entryId]=$KALTURA_ENTRY_ID"
```


4. Generate a user KS with entitlement for the matching privacy context:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/session/action/start" \
  -d "format=1" \
  -d "partnerId=$KALTURA_PARTNER_ID" \
  -d "secret=$KALTURA_ADMIN_SECRET" \
  -d "type=0" \
  -d "userId=jane.doe@example.com" \
  -d "privileges=enableentitlement,privacycontext:myapp"
```


Only `jane.doe@example.com` (a category member) can see entries in this category when using this KS. Other users with entitlement enabled for the same `privacycontext` who are not category members cannot see the entries.

### Backward Compatibility Note

The `KalturaBaseEntry` exposes `categories` and `categoriesIds` properties. These properties work only when categories are NOT configured with entitlement settings. Use the `categoryEntry` service to manage category assignments in all cases.