# Roles

Roles are named collections of [Permissions](#tag/Permissions) that define what actions
a user can perform across the platform. The platform uses a hierarchical RBAC model where
users are assigned roles (directly or via [User Groups](#tag/User-Groups)), and those roles
carry the permissions that gate access to API operations and content resources.

Role operations:
- **Create / Update** — define a role and specify which permissions it grants
- **Retrieve / List** — inspect role definitions across the organization
- **Activate / Disable** — toggle a role without deleting it; disabling a role
  immediately removes its permissions from all assigned users
- **Purge** — permanently delete a role

Roles are evaluated alongside fine-grained resource policies managed by
[Access Control](#tag/Access-Control) to produce the final authorization decision
for any given user and resource combination.


## Create a role

 - [POST /api/v1/role/create-role](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.createrole.md): Creates a new role of the given type with an initial set of permissions.

Request:
name              - Display name for the role.
roleType         - Whether this is a USER_ROLE (assigned to individual users) or a
GROUP_ROLE (assigned to user groups).
description       - Description of what this role grants.
permissionIds    - Non-empty list of permission IDs to associate with the role.

Response:
id                - Assigned role ID.
name              - Role display name.
roleType         - The role type.
description       - Role description.
permissionIds    - List of permission IDs associated with the role.

## Search roles

 - [POST /api/v1/role/list-roles](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.listroles.md): Lists roles within the organization, with optional filtering by type or disabled status.

Request:
includeDisabled  - When true, includes disabled roles in the results.
roleType         - Optional filter to return only USER_ROLE or GROUP_ROLE roles.

Response:
roles             - List of RoleItem objects including id, name, type, description,
permissionIds, and whether the role is a system role.

## Get a role

 - [POST /api/v1/role/retrieve-role](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.retrieverole.md): Retrieves full role details by their IDs.

Request:
roleIds   - List of role IDs to retrieve.

Response:
roles      - List of RoleItem objects matching the requested IDs.

## Update a role

 - [POST /api/v1/role/update-role](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.updaterole.md): Updates the name, description, and permission set of an existing role.

Request:
id                - ID of the role to update.
name              - New display name.
description       - New description.
permissionIds    - Replacement list of permission IDs. Must be non-empty.

Response:
id                - ID of the updated role.
name              - Updated display name.
roleType         - Role type (unchanged).
description       - Updated description.
permissionIds    - Updated list of permission IDs.

## Disable roles

 - [POST /api/v1/role/disable-roles](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.disableroles.md): Soft-disables one or more roles, making them inactive without permanent deletion.

Request:
ids   - List of role IDs to disable.

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

## Permanently remove roles

 - [POST /api/v1/role/purge-roles](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.purgeroles.md): Permanently deletes one or more roles and their associated permission records.

Request:
ids   - List of role IDs to permanently delete.

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

## Activate roles

 - [POST /api/v1/role/activate-roles](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.activateroles.md): Re-enables one or more previously disabled roles.

Request:
ids   - List of role IDs to activate.

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