# API-Referenz Benutzerverwaltung (App-Kennung benutzerverwaltung)

> 3 App-Tools. Aufruf immer mit `POST /api/app-tools`, Header `X-API-KEY`, Body `{"name": "<tool>", "input": {…}}`. Welche Tools ein Schlüssel nutzen darf, zeigt `GET /api/app-tools` der Instanz.

Quelle: https://support.unitedsynergy.com/api/referenz/benutzerverwaltung/

## Datenobjekte

Die Standard-Aktionen je Datenobjekt: list (suchen und blättern), get (einen Datensatz lesen), create, update und delete. Nicht jedes Objekt bietet alle fünf an.

### Personen / Benutzer: `benutzerverwaltung.person.*`

#### benutzerverwaltung.person.list

Liste/Suche: Personen / Benutzer

- Art: Lesen
- Rechte: Person lesen
- Datenklassen: C (vertraulich)
- Eingabe:
  - `search` (string): Freitextsuche
  - `filters` (object): Feld=Wert-Filter
  - `limit` (integer)
  - `offset` (integer)
  - `orderBy` (string)
- Beispiel: `{"name":"benutzerverwaltung.person.list","input":{}}`

#### benutzerverwaltung.person.get

Detail: Personen / Benutzer

- Art: Lesen
- Rechte: Person lesen
- Datenklassen: C (vertraulich)
- Eingabe:
  - `id` (string, Pflicht)
- Beispiel: `{"name":"benutzerverwaltung.person.get","input":{"id":"<id>"}}`

## Weitere Aktionen

Eigene Aktionen der App, zum Beispiel Auswertungen, Versand, Zuordnungen oder Abläufe über mehrere Datensätze.

#### benutzerverwaltung.onboard

Legt eine Person an; mit E-Mail zusätzlich Login-Account + Tenant-Mitgliedschaft mit Rollen (tenant_roles.slug). invite=false (Default) provisioniert nur, invite=true versendet den Magic-Link. Idempotent auf E-Mail (existierender User wird verlinkt). Admin-Rollen sind gesperrt. Für Bulk-Onboarding je Kunde.

- Art: Anlegen, vor dem Ausführen ausdrücklich bestätigen lassen
- Rechte: Benutzer anlegen
- Datenklassen: C (vertraulich)
- Datenschutz: Legt personenbezogene Stammdaten + Login-Account tenant-isoliert an. Rollen werden nur gesetzt, Admin-Rollen sind gesperrt (Privilege-Escalation-Schutz).
- Eingabe:
  - `vorname` (string, Pflicht)
  - `nachname` (string, Pflicht)
  - `email` (string): E-Mail für den Login-Account. Ohne E-Mail wird nur eine Person (Stammdaten) angelegt
  - `rollen` (string[]): Rollen-Slugs (tenant_roles.slug), Mehrfachauswahl. Admin-Rollen werden abgelehnt
  - `invite` (boolean): true = Magic-Link (Einladung) sofort versenden. Default false = nur Konto anlegen
  - `mitLogin` (boolean): Login-Account anlegen. Default true wenn E-Mail vorhanden
  - `anrede` (string)
  - `titel` (string)
  - `telefon` (string)
  - `mobil` (string)
- Beispiel: `{"name":"benutzerverwaltung.onboard","input":{"vorname":"<vorname>","nachname":"<nachname>"}}`