Users-API

Users-API

Die Users-API ermöglicht das Abfragen und Verwalten von Benutzer-Datensätzen. Alle Endpoints erfordern ein gültiges Access-Token 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.

POST /api/users erstellt das Konto direkt und weist keine Gruppen zu. Soll die Person ihr Passwort selbst wählen, von Anfang an in den richtigen Gruppen landen und im Rahmen der Registrierung eine SSO-Anmeldung verknüpfen, versende stattdessen eine Einladung — siehe Einen Benutzer einladen.

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.
• newMobileNumber — die Nummer, an die SMS- und Anruf-Benachrichtigungen gehen. Ein leerer oder ausschließlich aus Leerzeichen bestehender value leert das Feld.
• newRemoteSupportDisplayName — der Name, der während des Fernsupports auf dem Kundengerät angezeigt wird. Ein leerer oder ausschließlich aus Leerzeichen bestehender value leert das Feld, und es wird der Name des Benutzers angezeigt.
• newTotpSecret — ein value von null deaktiviert TOTP.
• oidcProvidersToUnlink — zu entkoppelnde OIDC-Anbieter, z. B. ["Microsoft"].

Die Gruppenzugehörigkeit ist nicht Teil dieser Anfrage. Die Gruppen eines Benutzers werden über POST /api/groups/{id} mit newMemberUserIds zugewiesen; das erfordert die Berechtigung groups.manage — siehe Groups-API.

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.

Einen Benutzer löschen

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

Einen Benutzer einladen

POST /api/user-invitations

Erfordert die Berechtigung users.manage. Eine Einladung hält fest, wer aufgenommen werden soll, und schickt der Person per E-Mail einen Link; das Konto selbst entsteht erst beim Annehmen. Erforderlich: mailAddress und lastname. firstname ist optional. groupIds legt die Gruppen fest, denen das neue Konto beim Annehmen beitritt, und erfordert zusätzlich die Berechtigung groups.manage — ohne sie liefert die Anfrage 403 Forbidden. Die Antwort enthält die id der Einladung sowie die Einladungs-URL, sodass du den Link auch über einen anderen Kanal weitergeben kannst.

Zum Annehmen gibt es zwei Wege: ein Passwort über POST /api/user-invitations/accept setzen (mindestens 8 Zeichen) oder sich mit einem OIDC-Anbieter anmelden, wodurch dieser Anbieter mit dem neuen Konto verknüpft wird. In beiden Fällen fällt jede Gruppe aus der Zuweisung, die zwischen Einladung und Annahme gelöscht wurde.

Validierungsregeln

• Eine leere oder ausschließlich aus Leerzeichen bestehende mailAddress liefert 400 Bad Request.
• Eine Adresse, die bereits zu einem Benutzer gehört oder für die bereits eine offene Einladung existiert, liefert 400 Bad Request.
• groupIds mit einer unbekannten Gruppen-ID liefert 400 Bad Request.
• Einladungen laufen 7 Tage nach dem Versand ab. POST /api/user-invitations/{id}/resend schickt den Link erneut und setzt diese 7 Tage neu; ein Aufruf innerhalb von 60 Sekunden nach dem letzten Versand liefert 429 Too Many Requests.
• POST /api/user-invitations/accept liefert 404 Not Found bei einem unbekannten oder bereits angenommenen Token, 410 Gone bei einem abgelaufenen, 400 Bad Request bei einem Passwort mit weniger als 8 Zeichen und 409 Conflict, wenn zwischenzeitlich ein Benutzer mit dieser Adresse angelegt wurde.

GET /api/user-invitations listet alle Einladungen auf, die neuesten zuerst, einschließlich der bereits angenommenen und widerrufenen. Das Feld status unterscheidet sie.

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.
• newMobileNumber — die Nummer, an die deine SMS- und Anruf-Benachrichtigungen gehen. Ein leerer oder ausschließlich aus Leerzeichen bestehender value leert das Feld.
• 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 bleibt das Passwort bestehen, bis eine andere Anmeldung verknüpft ist. 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.
• locale — deine Profilsprache, zum Beispiel de. SMS-, Anruf- und App-Push-Benachrichtigungen werden in dieser Sprache versendet; ist sie nicht gesetzt, greifen SMS und Anruf auf Englisch zurück und Push auf die Gerätesprache. Ein leerer oder ausschließlich aus Leerzeichen bestehender Wert leert das Feld.
• welcomeSeen — ob du den Willkommensdialog bereits gesehen hast. Die Weboberfläche setzt dies auf true, sobald du ihn schließt.

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. In diesem Objekt nur lesbar — die Zugehörigkeit wird über die Groups-API gesetzt.
• 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.