# User Groups

User Groups organize users into named collections for streamlined access control
and administration. Instead of assigning roles and permissions user-by-user, you assign
them to a group and manage membership centrally.

Groups support a full lifecycle:
- **Create / Update / Retrieve / List** — manage group definitions
- **Add Member / Revoke Member** — control who belongs to the group
- **Activate / Disable** — enable or suspend a group without deleting it;
  disabled groups do not grant their members any access
- **Purge** — permanently remove a group and its membership records

Groups integrate with the [Roles](#tag/Roles) and [Access Control](#tag/Access-Control)
systems, and are a key building block for multi-tenant or brand-scoped permission models.


## Create a user group

 - [POST /api/v1/user-group/create-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.createusergroup.md): Creates a new user group with an optional parent group for hierarchical organization.

Request:
name              - Display name of the user group.
description       - Description of the group's purpose or membership criteria.
parentGroupId   - Optional ID of an existing group to nest this group under.

Response:
userGroup        - The created UserGroupItem containing the assigned id, name,
description, and parentGroupId.

## Search user groups

 - [POST /api/v1/user-group/list-user-groups](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.listusergroups.md): Lists user groups within the organization, with optional filtering by parent or status.

Request:
includeDisabled    - When true, includes disabled groups in the results.
parentGroupId     - Optional parent group ID to return only direct child groups.

Response:
userGroups         - List of UserGroupItem objects matching the filter criteria.

## Disable a user group

 - [POST /api/v1/user-group/disable-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.disableusergroup.md): Soft-disables one or more user groups, cascading to all child groups recursively.

Request:
ids   - List of user group IDs to disable. All descendant groups are also disabled.

Response:
ids   - List of IDs of the groups that were successfully disabled.

## Permanently remove a group

 - [POST /api/v1/user-group/purge-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.purgeusergroup.md): Permanently deletes one or more user groups along with their memberships.

Request:
ids   - List of user group IDs to permanently delete.

Response:
ids   - List of IDs of the groups that were successfully purged.

## Update a user group

 - [POST /api/v1/user-group/update-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.updateusergroup.md): Updates the name and description of an existing user group.

Request:
id            - ID of the user group to update.
name          - New display name for the group.
description   - New description for the group.

Response:
id            - ID of the updated group.
name          - Updated display name.
description   - Updated description.

## Add member to group

 - [POST /api/v1/user-group/user-group-add-member](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.usergroupaddmember.md): Adds one or more users to a user group. Idempotent — adding an existing member succeeds silently.

Request:
groupId    - ID of the user group to add members to.
userIds    - List of user IDs to add to the group.

Response:
userIds    - List of user IDs that were successfully added.

## Remove member from group

 - [POST /api/v1/user-group/user-group-revoke-member](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.usergrouprevokemember.md): Removes one or more users from a user group. Idempotent — removing a non-member succeeds silently.

Request:
groupId    - ID of the user group to remove members from.
userIds    - List of user IDs to remove from the group.

Response:
userIds    - List of user IDs that were successfully removed.

## Get a user group

 - [POST /api/v1/user-group/retrieve-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.retrieveusergroup.md): Retrieves user group details by their IDs.

Request:
ids           - List of user group IDs to retrieve.

Response:
userGroups   - List of UserGroupItem objects matching the requested IDs.

## Activate a user group

 - [POST /api/v1/user-group/activate-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.activateusergroup.md): Re-enables one or more previously disabled user groups.

Request:
ids   - List of user group IDs to activate.

Response:
ids   - List of IDs of the groups that were successfully activated.