User To Group Location

Reference for the user_to_group_location 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

Not available as a standard REST operation for this resource: create, update, delete — such requests return 402 feature_not_enabled or 403 permission_denied (see the actions above for this resource's write path).

How it works

user_to_group_location assigns a user to a permission group at a location — this is what gives a user their permissions, so it's the step that makes a freshly-created user (see users) actually functional. A user with no assignments can log in but sees nothing; each assignment grants that user the group's permissions at that location.

A row is glid (a group-location — one group configured at one location, from group_to_location)

• uid (the user). You assign by user + group + location; the API resolves the group-location for you.

Note. Assigning or unassigning updates the user's whole permission set atomically — not just this pivot. Each call re-syncs the user's location membership and rebuilds their effective permissions, so a freshly-created user becomes viewable and functional immediately after their first assignment, and removing their last assignment revokes all access. (This mirrors the admin UI, which saves the complete set in one operation.)

Gated by the User Groups permission (a view-bit manage permission — every operation checks the same View bit). You must also not be restricted from managing user permission-group information. The assignments of SecurityTrax's reserved internal administrator account can only be managed by SecurityTrax staff.

This resource has a composite primary key (glid, uid) and no row id. An assignment is identified by (user, group, location), so there is no GET/PATCH/DELETE /user_to_group_location/{id}. You read assignments (list) and assign / unassign them through the two collection actions below. The group must already be configured at the location (its group_to_location row must exist) — this resource does not create those.

Assigning a user

POST /user_to_group_location/set assigns a user to a group at a location. Idempotent: if the user is already in that group at that location, the existing assignment is returned unchanged.

curl -X POST "https://portal.securitytrax.com/acme/user/v4/user_to_group_location/set" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"uid":42,"group_id":5,"location_id":1}}}'

Returns the resulting assignment (201), including the computed group_id and location_id. A group not configured at that location, or an unknown user, returns 422.

Unassigning a user

POST /user_to_group_location/clear removes a user's assignment to a group at a location. Removing one that doesn't exist returns 404.

curl -X POST "https://portal.securitytrax.com/acme/user/v4/user_to_group_location/clear" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"uid":42,"group_id":5,"location_id":1}}}'

Reading assignments

GET /user_to_group_location?uid={userId} lists a user's group assignments (filters: uid, glid; sort: glid, uid, created_at; ?count_only=true for the total). Each row includes the computed group_id and location_id so you can read the assignment without decoding the glid. This is how you confirm a newly-created user has been granted access.

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.

User Group Location

View: special access rules. Create: special access rules.

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: uid, glid. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

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

Related

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