Users-API

Users-API

Die Users-API ermöglicht das Abfragen und Verwalten von Benutzer-Datensätzen. Alle Endpoints erfordern ein gültiges JWT im Authorization: Bearer <token>-Header — wie du eines erhältst, erfährst du unter API-Authentifizierung.

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. Dieser Artikel behält nur die Berechtigungen, Verhaltensweisen und Validierungsregeln, die das Schema nicht ausdrücken kann.

Endpoints

Aktuellen Benutzer abrufen

GET /api/users/me gibt eine sitzungsbezogene Ansicht des authentifizierten Aufrufers zurück, deren Struktur vom regulären User-Objekt abweicht: Das E-Mail-Feld heißt email (nicht mailAddress), die vollständigen groups-Objekte werden mit ihren aufgelösten Berechtigungen zurückgegeben (nicht nur groupIds), und ein zusätzliches Feld preferences ist enthalten. Die feldweisen Details findest du in Swagger.

Einen Benutzer erstellen

Erfordert die Berechtigung users.manage. Erforderlich: mailAddress (die Login-E-Mail-Adresse, die eindeutig sein muss) und lastname. firstname und password sind optional; die vollständige Feldliste findest du in Swagger.

Wird ein Benutzer ohne Passwort erstellt, hat dieser keinen lokalen Passwort-Login und benötigt einen verknüpften OIDC / SSO Login, bevor eine Anmeldung möglich ist. Ein gängiges Beispiel ist Microsoft SSO. Bei Microsoft SSO kann die erste Anmeldung eine Zustimmung durch einen Microsoft-Administrator im Microsoft-Tenant erfordern, um octoja zu autorisieren.

Einen Benutzer aktualisieren

POST /api/users/{id}

Erfordert die Berechtigung users.manage. 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. Ein nackter Wert (zum Beispiel "newFirstname": "Max") wird als Deserialisierungsfehler abgelehnt. Die vollständige Liste der aktualisierbaren Felder findest du in Swagger; die folgenden Felder tragen erwähnenswertes Verhalten:

{  "newFirstname": { "hasValue": true, "value": "Max" },  "newPassword": { "hasValue": true, "value": null }}

• newMailAddress — neue Login-E-Mail-Adresse; muss eindeutig sein.
• newPassword — ein value von null entfernt den lokalen Passwort-Login und macht das Konto SSO-only, sofern nicht später ein neues Passwort gesetzt wird.
• newFirstname / newLastname — ein value von null leert den Namen.
• newGroupIds — ersetzt die vollständige Gruppenzuweisungsliste (kein partielles Hinzufügen/Entfernen).
• newTotpSecret — ein value von null deaktiviert TOTP.
• oidcProvidersToUnlink — zu entkoppelnde OIDC-Anbieter, z. B. ["Microsoft"].

Validierungsregeln

• newMailAddress mit einem leeren oder ausschließlich aus Leerzeichen bestehenden value oder einer bereits von einem anderen Benutzer verwendeten Adresse liefert 400 Bad Request.
• newPassword mit einem leeren oder ausschließlich aus Leerzeichen bestehenden value liefert 400 Bad Request — zum Entfernen des Passworts null verwenden.
• newGroupIds mit einer unbekannten Gruppen-ID liefert 400 Bad Request.
• Eine Gruppenänderung, die die letzte effektive groups.manage-Fähigkeit entfernen würde, wird durch die Sicherheitsprüfung abgelehnt.

Einen Benutzer löschen

Erfordert die Berechtigung users.manage. Dieselbe Sicherheitsprüfung greift auch hier: Das Löschen eines Benutzers wird abgelehnt, wenn danach kein Mitglied einer Gruppe mit der Berechtigung groups.manage mehr übrig bliebe.

Eigenes Profil aktualisieren

POST /api/users/me steht jedem authentifizierten Benutzer zur Verfügung — die Berechtigung users.manage ist nicht erforderlich. Die Felder verwenden dieselbe UpdateValue<T>-Hülle wie „Einen Benutzer aktualisieren", und der Endpoint liefert den aktualisierten Benutzer zurück. Erwähnenswertes Verhalten:

• newFirstname — ein value von null oder ein leerer String leert ihn.
• newLastname — ein leerer oder ausschließlich aus Leerzeichen bestehender value wird mit 400 Bad Request abgelehnt.
• newTotpSecret — ein value von null deaktiviert TOTP.
• oidcProvidersToUnlink — entkoppelt deine eigenen OIDC-Anmeldungen, zum Beispiel ["Microsoft"]. Wird mit 400 Bad Request abgelehnt, wenn dir dadurch keine Anmeldemöglichkeit mehr bliebe (kein lokales Passwort und keine verbleibende verknüpfte Anmeldung).

Eigenes Passwort ändern

POST /api/users/me/change-password

Steht jedem authentifizierten Benutzer zur Verfügung. Dieser Endpoint verwendet einfache Felder (currentPassword, newPassword), nicht die UpdateValue-Hülle. Er liefert 400 Bad Request, wenn eines der Felder leer ist, das Konto kein lokales Passwort gesetzt hat oder currentPassword falsch ist. Bei Erfolg ist die Antwort 204 No Content.

Eigenes Passwort entfernen

DELETE /api/users/me/password

Steht jedem authentifizierten Benutzer zur Verfügung. Dies entfernt dein lokales Passwort, sodass sich das Konto nur noch über SSO anmeldet. Es liefert 400 Bad Request, wenn kein Passwort gesetzt ist oder wenn das Konto keine verknüpfte OIDC-Anmeldung hat — octoja behält immer mindestens eine Anmeldemethode, daher kannst du das Passwort nicht von einem Konto entfernen, das keine andere Anmeldemöglichkeit hat. Bei Erfolg ist die Antwort 204 No Content.

Eigene Einstellungen aktualisieren

POST /api/users/me/preferences steht jedem authentifizierten Benutzer zur Verfügung und aktualisiert das preferences-Objekt, das GET /api/users/me zurückgibt. Es liefert das aktualisierte Einstellungsobjekt zurück. Erwähnenswertes Verhalten:

• toggleFavoriteAssetId — schaltet das Gerät in der Favoritenliste um: fügt es hinzu, wenn es fehlt, und entfernt es, wenn es vorhanden ist. Maximal 100 Favoriten; darüber hinaus wird das Hinzufügen mit 400 Bad Request abgelehnt.
• startPage — die Seite, die nach der Anmeldung angezeigt wird. Einer aus einer festen Menge von Werten (Dashboard, Cases, Devices, Customers, PatchCycles); Standard Dashboard.
• openDevicesInNewTab — ob Geräte-Links in einem neuen Browser-Tab geöffnet werden.

Wichtige Felder

Das vollständige User-Objekt ist in Swagger feldweise dokumentiert. Einige Felder tragen leicht zu übersehendes Verhalten:

• mailAddress — die Login-E-Mail-Adresse im Standard-User-Objekt; beachte, dass GET /api/users/me diese stattdessen als email zurückgibt.
• groupIds — die IDs der Gruppen, denen dieser Benutzer angehört; die aufgelösten Gruppenobjekte mit Berechtigungen liefert nur GET /api/users/me.
• hasPassword / hasTotpSecret — Booleans, die angeben, ob ein lokales Passwort bzw. TOTP gesetzt ist, ohne das Secret preiszugeben.
• oidcLogins — verknüpfte OIDC-Anmeldungen; jeder Eintrag trägt providerId (z. B. Microsoft), subjectId und linkedAt.