Groups

Reference for the groups resource. Requests follow the conventions in Requests and Responses; fields you receive and may write are filtered by your user's permissions, so responses can contain a subset of the fields below.

Operations

Operation	Request
List	`GET /{profile}/user/v4/groups`
Fetch	`GET /{profile}/user/v4/groups/{id}`
Create	`POST /{profile}/user/v4/groups`
Update	`PATCH /{profile}/user/v4/groups/{id}`
Delete	`DELETE /{profile}/user/v4/groups/{id}`

How it works

groups are the permission groups users are assigned to — each group bundles a set of permissions, and assigning a user to a group at a location (via user_to_group_location) grants those permissions there. You have full CRUD on the group row (name, description, assignable flag); a group's actual permission grants are managed in the SecurityTrax permissions editor, not through the API.

Reading requires the Group admin permission or the User Groups assignment permission; creating, editing, and deleting require the Group admin permission.

Creating / editing a group

curl -X POST "https://portal.securitytrax.com/acme/user/v4/groups" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"name":"Field Techs","about":"Installers and service techs","assignable":1}}}'

Field	Required	Notes
`name`	Yes	1–255 chars.
`about`	No	Description.
`assignable`	No	`1` (default) if the group may be assigned to users; `0` for structural groups.

A new group starts with no permission grants and no locations — configure both in the permissions editor before assigning users to it.

Deleting a group — guards

DELETE /groups/{id} soft-deletes a group, with two guards:

A group that still has members assigned (or is still referenced by the account system) cannot be deleted — 422. Unassign its users first.
System groups (including the SecurityTrax all-access group) cannot be modified or deleted — 403.

Listing groups

Filters: name (matches anywhere), assignable (true/false), and location_id — only groups configured at that location, i.e. valid group halves for a user_to_group_location set there. Sort by id, name, or created_at (default name); ?count_only=true for the total. GET /groups/{id} fetches one.

Tip. The assignment discovery flow is: GET /locations to pick a location → GET /groups?location_id={id}&assignable=true to see what's assignable there → POST /user_to_group_location/set.

Fields

Fields are grouped by the permission that gates them. A group you may not view is absent from responses; a group you may not write is rejected with 422 when sent in a write.

Group

View: any of: special access rules; special access rules. Create: Group. Update: Group.

Field	Type	Writable	Validation
`name`	string	Create, update	Required on create; max length 255
`about`	string (nullable)	Create, update	—
`assignable`	integer (nullable)	Create, update	one of: `0`, `1`
`created_at`	string (nullable)	Read-only	—
`created_by`	integer (nullable)	Read-only	—
`updated_at`	string (nullable)	Read-only	—
`updated_by`	integer (nullable)	Read-only	—

Pagination

The list endpoint uses client-controlled offset pagination: ?page= (1-based) and ?per_page= (default 25, max 100). The response mirrors meta.pagination (page, per_page, total, last_page) and sends an RFC5988 Link header; follow rel="next" to walk pages. See Pagination.

Filters

The list endpoint accepts these query-param filters: name, assignable, location_id. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../groups?sort= orders the list by: id, name, created_at. Prefix a field with - for descending; comma-separate for tie-breakers. An unsupported field returns 422. See Sorting collections.

Requests and Responses — envelope, errors, pagination, and rate limits.
Authentication — tokens and the Authorization header.