---
title: User Roles (RBAC)
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/user-management-user-roles-rbac
---

## User Roles (RBAC)


Roles define what permissions a user has. Each role is a set of named permissions. Assign roles to users via `user[roleIds]`.

### KalturaUserRole Object

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Auto-generated role ID (read-only) |
| `name` | string | Role display name |
| `systemName` | string | System-level name (for built-in roles) |
| `description` | string | Role description |
| `status` | integer | `1` = ACTIVE, `2` = BLOCKED, `3` = DELETED |
| `partnerId` | integer | `0` for system roles, your partner ID for custom roles |
| `permissionNames` | string | Comma-separated permission names |
| `tags` | string | Comma-separated tags |
| `createdAt` | integer | Unix timestamp (read-only) |
| `updatedAt` | integer | Unix timestamp (read-only) |

### Create a Role


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/userRole/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "userRole[objectType]=KalturaUserRole" \
  -d "userRole[name]=Content Viewer" \
  -d "userRole[description]=Read-only access to content" \
  -d "userRole[permissionNames]=BASE_USER_SESSION_PERMISSION,PLAYBACK_BASE_PERMISSION"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userRole[objectType]` | string | Yes | Always `KalturaUserRole` |
| `userRole[name]` | string | Yes | Role name |
| `userRole[description]` | string | No | Description |
| `userRole[permissionNames]` | string | Yes | Comma-separated permission names |
| `userRole[tags]` | string | No | Tags for categorization |

**Common permission names:**

| Permission | Description |
|------------|-------------|
| `BASE_USER_SESSION_PERMISSION` | Required for basic user sessions |
| `PLAYBACK_BASE_PERMISSION` | View/play content |
| `CONTENT_INGEST_UPLOAD` | Upload content |
| `CONTENT_MANAGE_BASE` | Basic content management |
| `CONTENT_MANAGE_DELETE` | Delete content |
| `CONTENT_MANAGE_METADATA` | Edit content metadata |
| `ADMIN_BASE` | Admin panel access |
| `ANALYTICS_BASE` | View analytics |

**Response:** Full `KalturaUserRole` object with generated `id`:


```json
{
  "id": 12345,
  "name": "Content Viewer",
  "systemName": "",
  "description": "Read-only access to content",
  "status": 1,
  "partnerId": 976461,
  "permissionNames": "BASE_USER_SESSION_PERMISSION,PLAYBACK_BASE_PERMISSION",
  "tags": "",
  "createdAt": 1718467200,
  "updatedAt": 1718467200,
  "objectType": "KalturaUserRole"
}
```


### Get a Role


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/userRole/action/get" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "userRoleId=$USER_ROLE_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userRoleId` | integer | Yes | Role ID to retrieve |

Returns the full `KalturaUserRole` object. Returns `USER_ROLE_NOT_FOUND` if the role does not exist.

### List Roles


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/userRole/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[objectType]=KalturaUserRoleFilter" \
  -d "filter[statusEqual]=1" \
  -d "filter[tagsMultiLikeOr]=custom" \
  -d "pager[pageSize]=50"
```


**Filter fields (`KalturaUserRoleFilter`):**

| Field | Description |
|-------|-------------|
| `idEqual` | Exact role ID |
| `idIn` | Comma-separated role IDs |
| `statusEqual` | `1` = ACTIVE, `2` = BLOCKED, `3` = DELETED |
| `nameEqual` | Exact name match |
| `systemNameEqual` | Exact system name match |
| `tagsMultiLikeOr` | Tags (OR match) |
| `orderBy` | `+id`, `-id`, `+createdAt`, `-createdAt` |

### Update a Role


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/userRole/action/update" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "userRoleId=$USER_ROLE_ID" \
  -d "userRole[objectType]=KalturaUserRole" \
  -d "userRole[description]=Updated permissions" \
  -d "userRole[permissionNames]=BASE_USER_SESSION_PERMISSION,PLAYBACK_BASE_PERMISSION,CONTENT_MANAGE_BASE"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userRoleId` | integer | Yes | Role ID to update |
| `userRole[objectType]` | string | Yes | Always `KalturaUserRole` |
| `userRole[name]` | string | No | Updated role name |
| `userRole[description]` | string | No | Updated description |
| `userRole[permissionNames]` | string | No | Updated comma-separated permission names (replaces all existing permissions) |
| `userRole[tags]` | string | No | Updated tags |

Fields not included remain unchanged. **Response:** Full updated `KalturaUserRole` object.

### Clone a Role


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/userRole/action/clone" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "userRoleId=$USER_ROLE_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userRoleId` | integer | Yes | Role ID to clone |

Creates a copy of an existing role. Useful for customizing built-in system roles without modifying the originals. **Response:** Full `KalturaUserRole` object for the new clone with a new `id`.

### Delete a Role


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/userRole/action/delete" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "userRoleId=$USER_ROLE_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userRoleId` | integer | Yes | Role ID to delete |

Sets `status=3` (DELETED). Users currently assigned this role retain it until their `roleIds` are updated.

### Assigning Roles to Users

Use `user.update` with the `roleIds` field to assign one or more roles:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/user/action/update" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "userId=jane.doe@example.com" \
  -d "user[objectType]=KalturaUser" \
  -d "user[roleIds]=$USER_ROLE_ID"
```


Use this role ID with the `setrole:ROLE_ID` KS privilege (see [Session Guide](/docs/getting-started/authentication/ks-overview)) to create sessions that inherit the role's permissions.