Benutzer-API

Die Benutzer-API bietet vollständiges Lebenszyklusmanagement für Benutzerkonten innerhalb eines Tenants: Erstellen, Lesen, Aktualisieren, Deaktivieren und Löschen von Benutzern; Rollenzuweisung; Massenimport und -export von Benutzern; und Verwaltung von Telefonnummern und Zwei-Faktor-Authentifizierungseinstellungen für einzelne Konten.

Alle Endpunkte in diesem Abschnitt erfordern den x-tenant-Header und, sofern nicht anders angegeben, die manage:users-Berechtigung.

Benutzerverwaltung

GET/api/usersRequires: manage:users

Alle Benutzer im Tenant auflisten. Unterstützt Paginierung und Filterung nach Rolle, Kontostatus und Suchanfrage. Gibt Benutzerobjekte mit zusammenfassenden Informationen zurück (enthält keine 2FA-Status oder Sitzungsdetails — verwende den einzelnen Benutzerendpunkt dafür).

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20, max: 100)
`search`	string	Volltextsuche über E-Mail, Benutzername, Vorname, Nachname
`role`	string	Nach Rollenname filtern
`status`	`active` \| `disabled` \| `locked`	Nach Kontostatus filtern

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "usr_abc123",
        "email": "[email protected]",
        "username": "alice",
        "firstName": "Alice",
        "lastName": "Smith",
        "enabled": true,
        "emailVerified": true,
        "createdAt": "2025-01-15T10:30:00Z",
        "roles": ["editor", "viewer"]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 87,
      "totalPages": 5
    }
  }
}

POST/api/usersRequires: manage:users

Ein neues Benutzerkonto im Tenant erstellen. Der Benutzer wird sowohl in der Auris-Datenbank als auch im zugrunde liegenden Keycloak-Realm erstellt. Wenn password weggelassen wird, wird das Konto ohne Passwort erstellt (der Benutzer muss es über einen Magic Link oder Passwort-Reset setzen).

Anforderungs-Body


{
  "email": "[email protected]",
  "username": "bob",
  "firstName": "Bob",
  "lastName": "Jones",
  "password": "anfangspasswort123",
  "roles": ["viewer"],
  "enabled": true
}

Alle Felder außer email sind optional.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "usr_def456",
    "email": "[email protected]",
    "username": "bob",
    "firstName": "Bob",
    "lastName": "Jones",
    "enabled": true,
    "emailVerified": false,
    "createdAt": "2025-02-18T09:00:00Z",
    "roles": ["viewer"]
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`EMAIL_TAKEN`	409	Ein Benutzer mit dieser E-Mail existiert bereits im Tenant
`USERNAME_TAKEN`	409	Benutzername ist bereits in Verwendung
`VALIDATION_ERROR`	400	Anforderungs-Body hat Schemavalidierung nicht bestanden

GET/api/users/[id]Requires: manage:users

Einen einzelnen Benutzer anhand seiner ID abrufen. Gibt vollständige Benutzerdetails zurück, einschließlich Rollenmitgliedschaften, 2FA-Status, Telefonnummer, Gruppenmitgliedschaften und letzte Anmeldeinformationen.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "username": "alice",
    "firstName": "Alice",
    "lastName": "Smith",
    "enabled": true,
    "emailVerified": true,
    "phoneNumber": "+49 30 12345678",
    "phoneNumberVerified": true,
    "createdAt": "2025-01-15T10:30:00Z",
    "lastLoginAt": "2025-02-17T14:22:00Z",
    "roles": ["editor", "viewer"],
    "twoFactor": {
      "totpEnabled": true,
      "smsEnabled": false,
      "webauthnEnabled": false
    }
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	Benutzer existiert nicht in diesem Tenant

PUT/api/users/[id]Requires: manage:users

Profilfelder eines Benutzers aktualisieren. Alle Felder sind optional — nur bereitgestellte Felder werden aktualisiert. Um einen Benutzer ohne Löschen zu deaktivieren, setze enabled: false.

Anforderungs-Body


{
  "firstName": "Alicia",
  "lastName": "Smith-Jones",
  "enabled": false
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "firstName": "Alicia",
    "lastName": "Smith-Jones",
    "enabled": false
  }
}

DELETE/api/users/[id]Requires: manage:users

Einen Benutzer soft-löschen. Das Benutzerkonto wird deaktiviert und in der Auris-Datenbank als gelöscht markiert, und sein Keycloak-Konto wird entfernt. Aktive Sitzungen werden sofort ungültig.

Soft-Deletion ist über die API irreversibel. Der Benutzerdatensatz wird in der Datenbank für Audit-Protokoll-Konsistenz aufbewahrt, kann aber nicht wiederhergestellt oder angemeldet werden. Verwende enabled: false über PUT /api/users/[id], wenn du vorübergehend deaktivieren möchtest ohne zu löschen.

Erfolgsantwort


{
  "ok": true,
  "data": { "deleted": true }
}

Rollenzuweisung

GET/api/users/[id]/rolesRequires: manage:users

Alle einem Benutzer derzeit zugewiesenen Rollen auflisten.

Erfolgsantwort


{
  "ok": true,
  "data": [
    {
      "id": "role_123",
      "name": "editor",
      "description": "Kann Inhalte erstellen und bearbeiten",
      "color": "#3b82f6"
    }
  ]
}

POST/api/users/[id]/rolesRequires: manage:users

Einem Benutzer eine Rolle zuweisen. Die Rolle muss im Tenant existieren. Dieselbe Rolle zweimal zuzuweisen ist ein No-Op (idempotent).

Anforderungs-Body


{
  "roleId": "role_123"
}

Erfolgsantwort


{
  "ok": true,
  "data": { "assigned": true }
}

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	Rolle existiert nicht in diesem Tenant
`SELF_ROLE_CHANGE`	403	Eigene Rollen können nicht geändert werden

DELETE/api/users/[id]/rolesRequires: manage:users

Eine Rolle von einem Benutzer entfernen. Eine Rolle zu entfernen, die der Benutzer nicht hat, ist ein No-Op (idempotent).

Anforderungs-Body


{
  "roleId": "role_123"
}

Erfolgsantwort


{
  "ok": true,
  "data": { "removed": true }
}

Massenimport

POST/api/users/importRequires: manage:users

Benutzer massenweise aus einer CSV- oder JSON-Datei importieren. Der Import läuft asynchron — der Endpunkt gibt sofort eine Job-ID zurück. Frage GET /api/users/import/[id] ab, um den Fortschritt zu verfolgen.

Anforderungsformat: multipart/form-data

Feld	Typ	Beschreibung
`file`	binary	CSV- oder JSON-Datei
`format`	`csv` \| `json`	Dateiformat
`sendWelcomeEmail`	boolean	Willkommens-E-Mail an neue Benutzer senden (Standard: false)

CSV-Format (erste Zeile ist Kopfzeile):


email,firstName,lastName,username,password,roles
[email protected],Alice,Smith,alice,,viewer
[email protected],Bob,Jones,bob,TempPass123,editor

JSON-Format:


[
  {
    "email": "[email protected]",
    "firstName": "Alice",
    "lastName": "Smith",
    "roles": ["viewer"]
  }
]

Erfolgsantwort (Job erstellt)


{
  "ok": true,
  "data": {
    "jobId": "import_xyz789",
    "status": "pending",
    "totalRows": 142,
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

GET/api/users/importRequires: manage:users

Alle Importjobs für den aktuellen Tenant auflisten, nach Erstellungszeit absteigend geordnet.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "import_xyz789",
        "fileName": "benutzer-2025-02.csv",
        "format": "csv",
        "status": "completed",
        "totalRows": 142,
        "processedRows": 142,
        "successCount": 140,
        "errorCount": 2,
        "createdAt": "2025-02-18T10:00:00Z",
        "completedAt": "2025-02-18T10:01:34Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 5, "totalPages": 1 }
  }
}

GET/api/users/import/[id]Requires: manage:users

Den aktuellen Status und Fehlerdetails eines Importjobs abrufen.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "import_xyz789",
    "status": "completed",
    "totalRows": 142,
    "processedRows": 142,
    "successCount": 140,
    "errorCount": 2,
    "errors": [
      {
        "row": 45,
        "email": "schlecht@",
        "error": "Ungültige E-Mail-Adresse"
      },
      {
        "row": 98,
        "email": "[email protected]",
        "error": "E-Mail bereits vorhanden"
      }
    ]
  }
}

Importjob-Status: pending, processing, completed, failed, partial.

Massenexport

POST/api/users/exportRequires: manage:users

Einen Benutzerexport auslösen. Der Export läuft asynchron. Frage GET /api/users/export ab, um den Job zu finden, dann lade ihn mit GET /api/users/export/[id]/download herunter, sobald der Status completed ist.

Anforderungs-Body


{
  "format": "csv"
}

format ist "csv" oder "json".

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "export_abc123",
    "status": "pending",
    "format": "csv",
    "createdAt": "2025-02-18T11:00:00Z"
  }
}

GET/api/users/exportRequires: manage:users

Alle Exportjobs auflisten.

GET/api/users/export/[id]/downloadRequires: manage:users

Die Exportdatei herunterladen, sobald der Jobstatus completed ist. Gibt die rohe Datei-Binärdatei mit einem entsprechenden Content-Disposition-Header zurück.

Exportdateien werden vorübergehend gespeichert und laufen nach 24 Stunden ab. Lade sie umgehend herunter, nachdem der Job abgeschlossen ist.

Telefonnummernverwaltung

Diese Endpunkte ermöglichen authentifizierten Benutzern, ihre eigene Telefonnummer zu verwalten. Keine besondere Berechtigung über ein gültiges Zugriffs-Token hinaus ist erforderlich.

POST/api/user/phone/setRequires: authenticated user

Die Telefonnummer des authentifizierten Benutzers setzen oder aktualisieren. Nach dem Setzen muss die Nummer mit POST /api/user/phone/verify verifiziert werden. Ein SMS-OTP wird an die angegebene Nummer gesendet.

Anforderungs-Body


{
  "phoneNumber": "+4930123456789"
}

Die Telefonnummer muss im E.164-Format sein (internationales Format mit Ländervorwahl).

Erfolgsantwort


{
  "ok": true,
  "data": {
    "sent": true,
    "phoneNumber": "+4930123456789"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`INVALID_PHONE`	400	Nummer ist nicht im E.164-Format
`PHONE_TAKEN`	409	Nummer ist bereits einem anderen Konto zugeordnet
`SMS_RATE_LIMITED`	429	Zu viele SMS-Anforderungen (max. 5 pro Stunde)

POST/api/user/phone/verifyRequires: authenticated user

Die Telefonnummer mit dem per SMS gesendeten OTP-Code verifizieren. Bei Erfolg wird phoneNumberVerified auf true im Benutzerkonto gesetzt.

Anforderungs-Body


{
  "code": "482910"
}

Erfolgsantwort


{
  "ok": true,
  "data": { "verified": true }
}

Fehlercodes

Code	HTTP	Beschreibung
`INVALID_OTP`	400	Code ist falsch
`OTP_EXPIRED`	400	Code ist abgelaufen (TTL: 10 Minuten)
`MAX_ATTEMPTS`	400	Maximale Verifizierungsversuche überschritten

Zwei-Faktor-Authentifizierung

POST/api/user/2fa/sms/enableRequires: authenticated user

SMS-OTP als 2FA-Methode für den authentifizierten Benutzer aktivieren. Erfordert eine verifizierte Telefonnummer. Ein OTP wird zur Bestätigung gesendet, dass das Telefon Codes empfangen kann, bevor es aktiviert wird.

Anforderungs-Body


{
  "code": "123456"
}

Gib das OTP an, das an die verifizierte Telefonnummer des Benutzers gesendet wurde.

Erfolgsantwort


{
  "ok": true,
  "data": { "smsEnabled": true }
}

Fehlercodes

Code	HTTP	Beschreibung
`PHONE_NOT_VERIFIED`	400	Benutzer hat keine verifizierte Telefonnummer
`INVALID_OTP`	400	Bestätigungscode ist falsch

POST/api/user/2fa/webauthn/enableRequires: authenticated user

Die WebAuthn-Passkey-Registrierungszeremonie starten, um WebAuthn als 2FA-Methode zu aktivieren. Gibt eine Registrierungsherausforderung zurück. Der Client muss die Zeremonie mit der WebAuthn-API des Browsers abschließen und die AuthenticatorAttestationResponse an POST /api/user/2fa/webauthn/challenge senden.

Anforderung: Kein Body erforderlich.

Erfolgsantwort (Registrierungsoptionen)


{
  "ok": true,
  "data": {
    "challenge": "base64url-challenge",
    "rp": { "name": "Auris", "id": "ihre-auris-domain.de" },
    "user": {
      "id": "base64url-user-id",
      "name": "[email protected]",
      "displayName": "Alice Smith"
    },
    "pubKeyCredParams": [{ "type": "public-key", "alg": -7 }],
    "timeout": 60000,
    "attestation": "none"
  }
}

Verwende die @simplewebauthn/browser-Bibliothek, um diese Herausforderung im Browser zu verarbeiten.

Zugehörige Referenzen

Benutzer verwalten — Anleitung zum Benutzerlebenszyklus-Management
Import & Export — Massenbenutzer-Migration über CSV/JSON
SCIM 2.0-Provisionierung — Automatisierte Benutzerbereitstellung
Benutzer & Rollen — Benutzer über die Konsole verwalten
Benutzerimport & -export API — Massenim- und -export-Endpunkte