# Permissions

Permissions are the atomic units of access control — named capabilities that define
what a user or role is allowed to do (e.g., `document:create`, `content:delete`,
`channel:manage`). Permissions are grouped into [Roles](#tag/Roles), which are then
assigned to users or [User Groups](#tag/User-Groups).

- `list-permissions` — enumerate all permissions defined in the platform; use this to
  understand what capabilities are available when designing custom roles
- `create-permission` — define a new named permission, typically used when extending
  the platform with custom action types or integration-specific access gates


## Search permissions

 - [POST /api/v1/permission/list-permissions](https://api.tenovos.com/openapi/content-intelligence/permissions/tenovos.authz.permissionservice.listpermissions.md): Lists all permissions defined in the system, with optional filtering by role.

Request:
roleId       - Optional role ID to return only permissions associated with that role.

Response:
permissions   - List of PermissionItem objects (id, name, description).

## Create a permission

 - [POST /api/v1/permission/create-permission](https://api.tenovos.com/openapi/content-intelligence/permissions/tenovos.authz.permissionservice.createpermission.md): Creates a new named permission that can be assigned to roles.

Request:
id            - Unique identifier for the permission (caller-supplied, not auto-generated).
name          - Human-readable display name.
description   - Optional description of what this permission grants.

Response:
permission    - The created PermissionItem.