# SECURITY ROLES Invoke the Security Roles API to retrieve, create, update, and delete Security Roles, and to retrieve the Permissions and Privileges that can be assigned to a Role to control what a user can see and do across the platform. ## Retrieve Roles - [GET /roles](https://api.tenovos.com/openapi/v1.5/security-roles/getroles.md): Response provides an array of the security Roles that are configured in Tenovos. The items returned are limited to the Roles available to the user making the API call. API User credentials must have administrative rights to the User Management privilege. Average Response Time: 274ms ## Retrieve Role Privileges - [GET /roles/privileges](https://api.tenovos.com/openapi/v1.5/security-roles/getprivileges.md): Response will include a list of all role privileges available in the system. The user making the request must have the 'Security Template Management' role privilege. All role privileges will be returned by default. User can pass 'enabled' or 'disabled' as a path parameter to return only enabled or disabled role privileges. The user making the request must have Role Management privilege. Average Response Time: 188ms ## Retrieve Security Permissions - [GET /security/permissions](https://api.tenovos.com/openapi/v1.5/security-roles/getsecuritypermissions.md): Response will include a list of all security permissions available in the system. The user making the request must have the Security Template Management role privilege. Average Response Time: 231ms ## (NEW!) List Security Roles (Paginated) - [GET /security/roles](https://api.tenovos.com/openapi/v1.5/security-roles/listsecurityroles.md): Retrieve a paginated, searchable list of the security roles configured for the authenticated customer. Defaults: - sortField defaults to roleName. - order defaults to asc. - from defaults to 0. - limit defaults to 100 (clamped to 100 if a higher value is supplied). Business Rules: - searchTerm is a case-insensitive substring match on role name. Special LIKE characters (%, _, \) are treated as literal text, not wildcards. - consentForm is not included on list items — it only appears on the get-by-id detail. The user submitting the request must have the Role Management privilege. ## (NEW!) Create Security Role - [POST /security/roles](https://api.tenovos.com/openapi/v1.5/security-roles/createsecurityrole.md): Create a security role for the authenticated customer. Business Rules: - name must be 1-32 characters after trimming, and unique per customer, case-insensitively — enforced by a database constraint, so a race between two concurrent creates for the same name always resolves to exactly one winner and a 409 for the loser. - Any field not in {name, consentForm, privileges} is rejected with 400. Defaults: - consentForm defaults to "". null is treated as absent. - privileges defaults to []. Entries are de-duplicated case-insensitively. Validation: - Each privileges entry must be a syntactically valid UUID (400 if not), then must exist and be enabled in the customer's privilege catalog (422 if any id is unknown or disabled). The user submitting the request must have the Role Management privilege. ## (NEW!) Get Security Role - [GET /security/roles/{id}](https://api.tenovos.com/openapi/v1.5/security-roles/getsecurityrole.md): Retrieve the full detail of a single security role, including its consent form, granted privileges, and everywhere it's currently referenced. The user submitting the request must have the Role Management privilege. ## (NEW!) Update Security Role - [PATCH /security/roles/{id}](https://api.tenovos.com/openapi/v1.5/security-roles/updatesecurityrole.md): Partially update a security role. Only the fields present in the body are changed. Business Rules: - At least one of name, consentForm, or privileges must be present — a body with only expectedLastUpdatedEpoch, or an empty object, is rejected with 400. - privileges, if supplied, fully replaces the existing set — it is not merged. An empty array clears all privileges. Omitting privileges never disturbs the stored role document. - Renaming to the role's own current name (even differing only by case) is not a collision. Optimistic Concurrency: - expectedLastUpdatedEpoch is optional. If supplied and it doesn't match the role's current lastUpdatedEpoch, the write is rejected with 409 and code: STALE_UPDATE. The response body is returned in the same shape as GET /security/roles/{id}. The user submitting the request must have the Role Management privilege. ## (NEW!) Delete Security Role - [DELETE /security/roles/{id}](https://api.tenovos.com/openapi/v1.5/security-roles/deletesecurityrole.md): Permanently delete a security role the authenticated customer owns. There is no force-delete override. Delete Rules: - Role must exist for the authenticated customer. - Deletion is blocked when either at least one user is currently assigned the role, or at least one preset (upload or filter) still references it in its role_ids. Both conditions are checked and reported together — the response names every blocker at once, not just the first one found. - The role is not silently unassigned from users or stripped out of presets to allow the delete — the caller must resolve the blockers first. This action is permanent and cannot be undone. The user submitting the request must have the Role Management privilege.