# SECURITY GROUPS Invoke the Security User Groups API to retrieve, create, update, and delete Security User Groups used to organize users for the purpose of assigning security access. ## Retrieve Security Groups - [GET /security/groups](https://api.tenovos.com/openapi/v1.5/security-groups/getsecuritygroups.md): User will get the list of Security Groups available in the system. The user submitting the request must have administrator rights to User Management. In response user will get a list, containing group names and their corresponding group id. Average Response Time: 189ms ## (NEW!) List Security User Groups (Paginated) - [GET /security/user-groups](https://api.tenovos.com/openapi/v1.5/security-groups/listsecurityusergroups.md): Retrieve a paginated, searchable list of the security user groups configured for the authenticated customer. This endpoint only ever operates on type: security groups — there is no way to request channel groups through it. Defaults: - sortField defaults to groupName. - 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 group name. Special LIKE characters (%, _, \) are treated as literal text, not wildcards. - There is no type query parameter. Every group returned is type: security. Sending a type parameter of any value — including security — is rejected with 400; it is not silently ignored, and it never changes what's returned. Channel groups are created and managed exclusively by the Publishing flow under a separate privilege, never through this API. The user submitting the request must have the User Management privilege. ## (NEW!) Create Security User Group - [POST /security/user-groups](https://api.tenovos.com/openapi/v1.5/security-groups/createsecurityusergroup.md): Create a security user group for the authenticated customer. name is the only accepted field. Business Rules: - name must be 1-255 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. - type is not an accepted input field at all. Sending it, with any value, is rejected with 400 — the created group is always type: security; this is reflected in the response but can never be set by the caller. The user submitting the request must have the User Management privilege. ## (NEW!) Bulk Create Security User Groups - [POST /security/user-groups/bulk](https://api.tenovos.com/openapi/v1.5/security-groups/bulkcreatesecurityusergroups.md): Create multiple security user groups for the authenticated customer in a single all-or-nothing batch. Either every name in the batch is created, or none are — there is no partial success. Business Rules: - names must be a non-empty array of strings, maximum 50 entries per request. A batch over 50 names is rejected outright with a plain 400 ("maximum 50 user groups are allowed in a request") without itemizing individual names — this structural check runs before any per-name validation. - Each name follows the same rules as single-create (1-255 characters after trim). - A name repeated within the same request (case-insensitively, after trimming) is rejected — it is not silently de-duplicated. - All entries in one batch share the same createdEpoch/createdBy (one request, one actor, one timestamp), and each gets its own id. - There is no Location response header on this endpoint, since it creates multiple resources. The user submitting the request must have the User Management privilege. ## (NEW!) Get Security User Group - [GET /security/user-groups/{id}](https://api.tenovos.com/openapi/v1.5/security-groups/getsecurityusergroup.md): Retrieve the full detail of a single security user group, including everywhere it's currently referenced. Business Rules: - Returns 404 if the group doesn't exist for the caller's customer, or if it exists but is type: channel — both cases are indistinguishable to the caller. The user submitting the request must have the User Management privilege. ## (NEW!) Rename Security User Group - [PATCH /security/user-groups/{id}](https://api.tenovos.com/openapi/v1.5/security-groups/updatesecurityusergroup.md): Rename a security user group. name is the only editable field on a group — unlike a role's PATCH, name is always required here, not "at least one of several fields." Business Rules: - type is not an accepted field here either — rejected with 400. - Caller identity is resolved first (401 if it can't be), then the group's existence is checked (404), then the concurrency guard (if supplied), then the name-uniqueness check. - If the exact same name (case-sensitive) already stored is resubmitted, the request is a true no-op — no uniqueness check runs and nothing is written, including no timestamp advance. Renaming to a case-only variant of the current name (e.g. "Hooli Corporate" → "HOOLI CORPORATE") is treated as a real change and does get written. Optimistic Concurrency: - expectedLastUpdatedEpoch is optional. If supplied and it doesn't match the group's current lastUpdatedEpoch, the write is rejected with 409 and code: STALE_UPDATE — checked before the name-uniqueness check, so a request that is both stale and a name collision surfaces STALE_UPDATE. The user submitting the request must have the User Management privilege. ## (NEW!) Delete Security User Group - [DELETE /security/user-groups/{id}](https://api.tenovos.com/openapi/v1.5/security-groups/deletesecurityusergroup.md): Permanently delete a security user group the authenticated customer owns. There is no force-delete override — mirrors role delete. Delete Rules: - Group must exist for the authenticated customer (or not be a channel-type group). - Deletion is blocked when either at least one user currently has this group, or at least one security template still references it. Both conditions are checked and reported together. - The group is not silently stripped from security templates or from users' memberships 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 User Management privilege.