Skip to main content

Role

Endpoints for managing roles.

📄️Create a new role for a tenant

Creates a new role under the tenant identified by the required `tenant-id` header. Use this to define a named grouping of permissions that can later be assigned to users; to modify an existing role use `PATCH /roles/{roleId}`. The request body accepts a `name` and an optional `description` for the new role. Returns 201 with the created role object including the server-assigned `id`, `tenantId`, `createdAt`, and `createdBy` fields. Returns 400 if the `tenant-id` header is absent or blank.

📄️Update an existing role's fields

Updates the role identified by `roleId` under the tenant specified by the required `tenant-id` header. Use this to change a role's name or description after creation; to create a new role use `POST /roles`. This is a full replacement, not a partial merge: any field omitted from the request body (`name` or `description`) is cleared on the role rather than left unchanged, so callers must resend the current value for any field they do not intend to change. Returns 200 with the full updated role object (`RoleResponseDto`). Returns 400 if the `tenant-id` header is absent or blank. Note: if the role does not exist, the current implementation returns 500 rather than 404 (tracked in CP-36405).

📄️Fetch a single role by its ID

Returns the full details of the role identified by `roleId` within the tenant specified by the required `tenant-id` header. Use this when you already hold a role ID and need the role's name, description, and metadata; to list all available roles use `GET /roles`. The `roleId` path parameter is the string identifier returned when the role was created (e.g. `'role-123-456-789'`). Returns a single role object (`RoleResponseDto`) on success. Returns 400 if the `tenant-id` header is absent or blank. Note: if no role with the given ID exists, the current implementation returns 500 rather than 404 (tracked in CP-36405); verify the ID against `GET /roles` to find valid values.

📄️List all permissions assigned to a role

Returns the full list of permissions currently assigned to the role identified by `roleId` within the tenant specified by the required `tenant-id` header. Use this to inspect what a role grants before assigning it to a user, or to determine which permissions need to be added or removed. The `roleId` is the string identifier returned when the role was created. Returns an array of permission objects (`PermissionResponseDto`) — the array will be empty if no permissions are assigned. Returns 400 if the `tenant-id` header is absent or blank. Note: if the role does not exist, the current implementation returns 500 rather than 404 (tracked in CP-36405).

📄️Add permissions to a role without removing existing ones

Adds one or more permissions to the role identified by `roleId`, leaving any existing permissions intact. Use this when you want to expand a role's permission set without affecting what it already has; to simultaneously add and remove permissions in one call use `PATCH /roles/{roleId}/permissions/bulk`. Requires the `tenant-id` header (returns 400 if absent or blank). The request body must include a `permissionIds` array of permission ID strings; obtain valid permission IDs from the permissions list endpoints. Returns 200 with the complete, updated list of all permissions now assigned to the role — not just the newly added ones. Note: if the role does not exist, the current implementation returns 500 rather than 404 (tracked in CP-36405).

📄️Add and remove role permissions in one call

Modifies the permission set of the role identified by `roleId` by adding and/or removing permissions in a single request. This is not a single atomic operation: the implementation reads the role's current permissions, merges the requested `add`/`remove` changes, and then writes the result back as a separate step (no transaction or rollback); concurrent calls for the same role may race, and one call's changes can be silently overwritten by another (tracked in CP-36406). Use this instead of separate add/remove calls when you need to both grant and revoke permissions in one operation; to only add permissions use `POST /roles/{roleId}/permissions`. Requires the `tenant-id` header (returns 400 if absent or blank). The request body accepts two optional arrays of permission ID strings: `add` (permissions to grant) and `remove` (permissions to revoke). Permissions in `remove` that are not currently assigned are silently ignored. If both `add` and `remove` include the same ID, the permission is added (remove is applied before add). Returns 200 with the complete, updated list of all permissions assigned to the role after the operation. Note: if the role does not exist, the current implementation returns 500 rather than 404 (tracked in CP-36405).