Groups-API

Gruppen erstellen, lesen, aktualisieren und löschen über die REST-API

Die Groups-API ermöglicht das Erstellen, Lesen, Aktualisieren und Löschen von Gruppen. Gruppen kombinieren ein Berechtigungsset mit einer Mitgliederliste — wird ein Benutzer einer Gruppe zugewiesen, erhält dieser die Berechtigungen der Gruppe.

Alle Endpoints erfordern ein gültiges Access-Token im Authorization: Bearer <token>-Header.

Die vollständige, stets aktuelle Liste der Endpoints, Parameter und Antwortfelder für die Version, die du betreibst, findest du in der interaktiven OpenAPI-Oberfläche (Swagger) unter https://<deine-octoja-instanz>/openapi/index.html.

Endpoints

OperationEndpointHinweise
Gruppen auflistenGET /api/groupsMit dem optionalen Parameter search nach Gruppenname filtern. Liefert ein Array von Group-Objekten zurück.
Eine Gruppe abrufenGET /api/groups/{id}Liefert 404 Not Found, wenn keine Gruppe mit der angegebenen id existiert.
Eine Gruppe erstellenPOST /api/groupsErfordert groups.manage. name ist erforderlich und muss mindestens ein Nicht-Leerzeichen enthalten; fehlende, leere oder ausschließlich aus Leerzeichen bestehende Werte werden mit 400 Bad Request abgelehnt. Liefert das erstellte Group-Objekt zurück.
Eine Gruppe aktualisierenPOST /api/groups/{id}Erfordert groups.manage. Verwendet die UpdateValue<T>-Hülle (siehe unten).
Eine Gruppe löschenDELETE /api/groups/{id}Erfordert groups.manage. Liefert 204 No Content (siehe unten).

Aktualisierungen erfolgen über POST /api/groups/{id}. PUT und PATCH sind für diese Ressource nicht registriert — eine Anfrage mit einem dieser Verben erreicht die Groups-API deshalb gar nicht. Sie landet in der Catch-all-Route der octoja-Weboberfläche und kommt als 200 OK mit einer HTML-Seite zurück. Prüfe daher den Content-Type der Antwort und nicht nur den Statuscode, wenn ein Client womöglich das falsche Verb sendet.

Wichtige Felder

  • isAdministratorGroup — kennzeichnet die Gruppe als Administratorgruppe. Führt ein octoja-Upgrade neue Berechtigungen ein, werden sie jeder Gruppe mit diesem Flag automatisch gewährt.
  • customerAccess — welche Kunden die Gruppe erreicht (Kundenzugriff). global umfasst alle Kunden; andernfalls erreicht die Gruppe die unter customerIds genannten Kunden sowie jeden Kunden, auf den das Regelwerk aus match und items zutrifft.
  • deviceAccess — welche Geräte die Gruppe innerhalb dieses Kundenbereichs erreicht (global, match, items) und was Mitglieder darauf tun dürfen (actions). Der Gerätezugriff schränkt den Kundenzugriff weiter ein, statt ihn zu erweitern — eine Gruppe ohne Kundenzugriff erreicht also keine Geräte.

Eine Gruppe aktualisieren

Sende nur die zu ändernden Felder. Jedes Feld wird in eine UpdateValue<T>-Hülle der Form { "hasValue": true, "value": <T> } verpackt; lass das Feld komplett weg, um es unverändert zu lassen. Aktualisierbar sind newName, newPermissions, newMemberUserIds, newIsAdministratorGroup, newCustomerAccess und newDeviceAccess. Ein nackter Wert (zum Beispiel "newName": "Support") wird als Deserialisierungsfehler abgelehnt. newPermissions und newMemberUserIds ersetzen jeweils die vollständige Liste, statt sie zusammenzuführen.

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

Validierung:

  • newName mit einem leeren oder ausschließlich aus Leerzeichen bestehenden value liefert 400 Bad Request.
  • Eine unbekannte Berechtigungs-ID in newPermissions liefert 400 Bad Request.
  • Eine unbekannte Benutzer-ID in newMemberUserIds liefert 400 Bad Request.
  • Regeln in newCustomerAccess dürfen nur CustomerTags, CustomField oder CustomerCustomField prüfen. Jedes andere Feld liefert 400 Bad Request.
  • Regeln in newDeviceAccess dürfen CustomerTags nicht prüfen — grenze stattdessen über newCustomerAccess nach Kunden ein. Andernfalls kommt 400 Bad Request zurück.
  • Das Entfernen der letzten effektiven groups.manage-Fähigkeit wird durch die Sicherheitsprüfung abgelehnt.

Eine Gruppe löschen

Beim Löschen einer Gruppe wird diese automatisch von allen Mitgliedern entfernt. Die Sicherheitsprüfung verhindert zudem das Löschen einer Gruppe, wenn dadurch keine Gruppe mehr zur Gruppenverwaltung übrig bliebe.

Verwandte Artikel