Groups API

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

Written By Erdinc Akay

Last updated 26 days ago

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 JWT 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 and return 404 Not Found.

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.

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. 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.
  • 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.