---
title: Groups
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/user-management-groups
---

## Groups


Groups are virtual users (`type=200`) that hold membership via the `groupUser` service. Use groups as recipients in the Messaging API, notification targets in the [Webhooks API](/docs/rich-media-cms-apis/integration/webhooks), or for content entitlement via category membership.

### Create a Group

Groups are created via the `group_group` service with `KalturaGroup`:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/group_group/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "group[objectType]=KalturaGroup" \
  -d "group[id]=engineering-team" \
  -d "group[screenName]=Engineering Team" \
  -d "group[tags]=department"
```


**Response:** A `KalturaGroup` object (status=1, membersCount=0). Delete groups via `group_group.delete` with `groupId`.

### Add User to Group


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/groupUser/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "groupUser[objectType]=KalturaGroupUser" \
  -d "groupUser[groupId]=engineering-team" \
  -d "groupUser[userId]=jane.doe@example.com"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `groupUser[objectType]` | string | Yes | Always `KalturaGroupUser` |
| `groupUser[groupId]` | string | Yes | Group ID (must exist with type=200) |
| `groupUser[userId]` | string | Yes | User ID to add to the group |

**Response:**


```json
{
  "userId": "jane.doe@example.com",
  "groupId": "engineering-team",
  "status": 0,
  "partnerId": 976461,
  "createdAt": 1718467200,
  "updatedAt": 1718467200,
  "objectType": "KalturaGroupUser"
}
```


### List Group Members


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/groupUser/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[objectType]=KalturaGroupUserFilter" \
  -d "filter[groupIdEqual]=engineering-team"
```


**Filter fields (`KalturaGroupUserFilter`):**

At least one of these is required:

| Field | Description |
|-------|-------------|
| `groupIdEqual` | List members of a specific group |
| `groupIdIn` | List members of multiple groups |
| `userIdEqual` | List groups a specific user belongs to |
| `userIdIn` | List groups for multiple users |

### Remove User from Group


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/groupUser/action/delete" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "userId=jane.doe@example.com" \
  -d "groupId=engineering-team"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userId` | string | Yes | User ID to remove from the group |
| `groupId` | string | Yes | Group ID to remove the user from |

Removes the user from the specified group. Returns nothing on success. Returns `INVALID_USER_ID` if the user is not a member of the group.

### Sync Group Membership

Replace all members of a group at once. Used by Auth Broker to sync IdP group claims to Kaltura groups:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/groupUser/action/sync" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "userId=jane.doe@example.com" \
  -d "groupIds=engineering-team,product-team"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userId` | string | Yes | User ID whose group membership to sync |
| `groupIds` | string | Yes | Comma-separated list of group IDs the user should belong to |
| `removeFromExistingGroups` | boolean | No | If `true` (default), removes the user from groups not in `groupIds`. If `false`, only adds to the specified groups without removing existing memberships. |
| `createNewGroups` | boolean | No | If `true`, creates groups from `groupIds` that do not exist yet. Default: `false`. |

Sets the user's group membership to exactly the specified groups, removing them from any groups not in the list (when `removeFromExistingGroups` is true).