Skip to main content
API Reference

Groups API

Create, read, update, and delete groups via the REST API.

The Groups API lets you create, read, update, and delete groups. Groups combine a permission set with a member list, so assigning a user to a group grants that user the group's permissions.

All endpoints require a valid access token in the Authorization: Bearer <token> header.

For the complete, always-current list of endpoints, parameters, and response fields for the version you are running, use the interactive OpenAPI (Swagger) interface at https://<your-octoja-instance>/openapi/index.html.

Endpoints

OperationEndpointNotes
List groupsGET /api/groupsOptional search query filters by group name. Returns an array of Group objects.
Get a groupGET /api/groups/{id}Returns 404 Not Found if no group exists with the given id.
Create a groupPOST /api/groupsRequires groups.manage. name is required and must contain a non-whitespace character; missing, empty, or whitespace-only is rejected with 400 Bad Request. Returns the created Group object.
Update a groupPOST /api/groups/{id}Requires groups.manage. Uses the UpdateValue<T> envelope (see below).
Delete a groupDELETE /api/groups/{id}Requires groups.manage. Returns 204 No Content (see below).

Updates use POST /api/groups/{id}. PUT and PATCH are not registered on this resource, so a request that uses either verb never reaches the Groups API — it falls through to the catch-all route of the octoja web interface and comes back as 200 OK with an HTML page. Check the content type of the response, not the status code alone, if a client might be sending the wrong verb.

Fields worth knowing

  • isAdministratorGroup — marks the group as an administrator group. When an octoja upgrade introduces new permissions, they are granted automatically to every group with this flag.
  • customerAccess — which customers the group reaches. global covers every customer; otherwise the group reaches the customers named in customerIds plus every customer matched by the rule set in match and items.
  • deviceAccess — which devices inside that customer scope the group reaches (global, match, items) and what members may do on them (actions). Device access narrows customer access rather than widening it, so a group that reaches no customers reaches no devices.

Update a group

Only send the fields you want to change. Each field is wrapped in an UpdateValue<T> envelope of the shape { "hasValue": true, "value": <T> }; omit the field entirely to leave it untouched. The updatable fields are newName, newPermissions, newMemberUserIds, newIsAdministratorGroup, newCustomerAccess, and newDeviceAccess. Sending a bare value (for example "newName": "Support") is rejected as a deserialization error. newPermissions and newMemberUserIds each replace the full list rather than merging.

{
  "newName": { "hasValue": true, "value": "Support" },
  "newPermissions": { "hasValue": true, "value": ["tickets.manage", "customers.manage"] }
}

Validation:

  • newName sent with an empty or whitespace-only value returns 400 Bad Request.
  • An unknown permission ID in newPermissions returns 400 Bad Request.
  • An unknown user ID in newMemberUserIds returns 400 Bad Request.
  • Rules in newCustomerAccess may only test CustomerTags, CustomField, or CustomerCustomField. Any other field returns 400 Bad Request.
  • Rules in newDeviceAccess may not test CustomerTags — narrow by customer in newCustomerAccess instead. Sending one returns 400 Bad Request.
  • Removing the last effective groups.manage capability is rejected by the safety guard.

Delete a group

Deleting a group removes it from all member users automatically. The safety guard also prevents deleting a group if that would leave no group able to manage groups.

Was this helpful?

Still need help? Ask the team