Benutzerimport & -export API

Die Benutzerimport & -export API ermöglicht Massenbenutzeroperationen für Migrations-, Onboarding- und Backup-Szenarien. Administratoren können Benutzer aus CSV- oder JSON-Dateien importieren und das vollständige Benutzerverzeichnis in einem der Formate exportieren.

Importvorgänge werden asynchron verarbeitet. Nach dem Hochladen einer Datei durchläuft der Import-Job Status-Phasen, während Zeilen validiert und Benutzer erstellt werden. Exportvorgänge sind ebenfalls asynchron — nach Abschluss ist die generierte Datei 24 Stunden lang zum Download verfügbar.

Benutzer importieren

Import-Datei hochladen

POST/api/users/importRequires: manage:users

Eine CSV- oder JSON-Datei mit zu importierenden Benutzerdatensätzen hochladen. Die Datei wird validiert und ein Import-Job erstellt. Die Verarbeitung erfolgt asynchron — frage den Job-Status ab, um den Fortschritt zu verfolgen. Maximale Dateigröße: 10 MB.

Anforderungs-Body — multipart/form-data

Feld	Typ	Erforderlich	Beschreibung
`file`	Datei	Ja	CSV- oder JSON-Datei (max. 10 MB). Dateiendung bestimmt das Format

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "imp_abc123",
    "fileName": "benutzer-stapel-2025-02.csv",
    "format": "csv",
    "status": "PENDING",
    "totalRows": 150,
    "processedRows": 0,
    "successCount": 0,
    "errorCount": 0,
    "errors": [],
    "createdAt": "2025-02-18T10:00:00Z",
    "updatedAt": "2025-02-18T10:00:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`VALIDATION_ERROR`	400	Datei fehlt, nicht unterstütztes Format, überschreitet 10-MB-Limit oder Datei ist leer
`PARSE_ERROR`	400	Datei konnte nicht geparst werden (fehlerhafte CSV oder ungültige JSON-Struktur)

Import-Jobs auflisten

GET/api/users/importRequires: manage:users

Alle Import-Jobs für den Tenant auflisten. Jobs sind nach Erstellungsdatum absteigend sortiert. Verwende diese Funktion, um laufende Importe zu überwachen oder die vergangene Import-Historie zu überprüfen.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20, max: 100)

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "imp_abc123",
        "fileName": "benutzer-stapel-2025-02.csv",
        "format": "csv",
        "status": "COMPLETED",
        "totalRows": 150,
        "processedRows": 150,
        "successCount": 142,
        "errorCount": 8,
        "createdAt": "2025-02-18T10:00:00Z",
        "updatedAt": "2025-02-18T10:05:00Z"
      },
      {
        "id": "imp_def456",
        "fileName": "migration-export.json",
        "format": "json",
        "status": "PARTIAL",
        "totalRows": 500,
        "processedRows": 500,
        "successCount": 487,
        "errorCount": 13,
        "createdAt": "2025-02-17T14:00:00Z",
        "updatedAt": "2025-02-17T14:12:00Z"
      },
      {
        "id": "imp_ghi789",
        "fileName": "fehlerhafte-datei.csv",
        "format": "csv",
        "status": "FAILED",
        "totalRows": 25,
        "processedRows": 3,
        "successCount": 0,
        "errorCount": 3,
        "createdAt": "2025-02-16T09:00:00Z",
        "updatedAt": "2025-02-16T09:00:30Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "totalPages": 1
    }
  }
}

Import-Job-Details abrufen

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

Detaillierte Informationen über einen Import-Job abrufen, einschließlich zeilenweise Fehlerdetails. Frage diesen Endpunkt ab, während status PENDING oder PROCESSING ist, um den Fortschritt zu verfolgen.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "imp_abc123",
    "fileName": "benutzer-stapel-2025-02.csv",
    "format": "csv",
    "status": "COMPLETED",
    "totalRows": 150,
    "processedRows": 150,
    "successCount": 142,
    "errorCount": 8,
    "errors": [
      {
        "row": 12,
        "email": "[email protected]",
        "error": "Email already exists in this tenant"
      },
      {
        "row": 34,
        "email": "invalid-email",
        "error": "Invalid email format"
      },
      {
        "row": 56,
        "email": "[email protected]",
        "error": "Role 'super_admin' does not exist"
      },
      {
        "row": 78,
        "email": "",
        "error": "Email is required"
      },
      {
        "row": 91,
        "email": "[email protected]",
        "error": "Email already exists in this tenant"
      },
      {
        "row": 102,
        "email": "[email protected]",
        "error": "Password does not meet minimum length requirement (8 characters)"
      },
      {
        "row": 119,
        "email": "eve@test",
        "error": "Invalid email format"
      },
      {
        "row": 133,
        "email": "[email protected]",
        "error": "Email already exists in this tenant"
      }
    ],
    "createdAt": "2025-02-18T10:00:00Z",
    "updatedAt": "2025-02-18T10:05:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	Import-Job existiert nicht

Verlauf des Import-Status

Import-Jobs durchlaufen diese Status:

Status	Beschreibung
`PENDING`	Datei hochgeladen und validiert, Verarbeitung noch nicht begonnen
`PROCESSING`	Zeilen werden verarbeitet. `processedRows` erhöht sich mit jeder verarbeiteten Zeile
`COMPLETED`	Alle Zeilen erfolgreich verarbeitet (`errorCount` ist 0)
`PARTIAL`	Alle Zeilen verarbeitet, aber einige hatten Fehler (`errorCount` > 0, `successCount` > 0)
`FAILED`	Verarbeitung vollständig fehlgeschlagen (Dateibeschädigung, Systemfehler oder alle Zeilen hatten Fehler)

Bei großen Importen (500+ Zeilen) kann die Verarbeitung mehrere Minuten dauern. Frage den Job-Detail-Endpunkt alle 2-3 Sekunden ab, um den Fortschritt zu verfolgen. Das Feld processedRows wird in Echtzeit aktualisiert.

Import-Dateiformate

CSV-Format

Die erste Zeile muss eine Kopfzeile mit Spaltennamen sein. Die Spaltenreihenfolge spielt keine Rolle. Spalten werden nach Name zugeordnet (Groß-/Kleinschreibung wird ignoriert).


email,firstName,lastName,roles,password
[email protected],Jane,Doe,editor,SecurePass123!
[email protected],Bob,Smith,"editor,viewer",AnotherPass456!
[email protected],Alice,Johnson,admin,
[email protected],Carol,Williams,,

Mehrere Rollen werden in Anführungszeichen kommagetrennt: "editor,viewer"
Leeres Passwortfeld bedeutet, dass der Benutzer Magic Link oder Passwort-Zurücksetzen verwenden muss
Leeres Rollenfeld bedeutet, dass der Benutzer ohne zugewiesene Rollen erstellt wird

JSON-Format

Die Datei muss ein JSON-Array von Benutzerobjekten auf oberster Ebene enthalten.


[
  {
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "roles": ["editor"],
    "password": "SecurePass123!"
  },
  {
    "email": "[email protected]",
    "firstName": "Bob",
    "lastName": "Smith",
    "roles": ["editor", "viewer"],
    "password": "AnotherPass456!"
  },
  {
    "email": "[email protected]",
    "firstName": "Alice",
    "lastName": "Johnson",
    "roles": ["admin"]
  },
  {
    "email": "[email protected]",
    "firstName": "Carol",
    "lastName": "Williams"
  }
]

Feldreferenz

Feld	Typ	Erforderlich	Beschreibung
`email`	string	Ja	E-Mail-Adresse des Benutzers. Muss innerhalb des Tenants eindeutig sein
`firstName`	string	Nein	Vorname des Benutzers
`lastName`	string	Nein	Nachname des Benutzers
`roles`	string/array	Nein	Zuzuweisende Rollennamen. Müssen vorhandenen Rollen im Tenant entsprechen
`password`	string	Nein	Anfangspasswort. Muss die Passwortrichtlinien des Tenants erfüllen

Passwörter sind optional. Wenn weggelassen, wird das Benutzerkonto ohne Passwort erstellt. Der Benutzer muss beim ersten Login einen Magic Link oder den Passwort-Zurücksetzen-Ablauf verwenden, um sein Passwort zu setzen. Dies ist der empfohlene Ansatz für Massenimporte.

Fehlerbehandlung pro Zeile

Jede Zeile wird unabhängig verarbeitet. Wenn eine Zeile die Validierung nicht besteht, wird sie übersprungen und der Fehler aufgezeichnet. Die Verarbeitung wird mit den verbleibenden Zeilen fortgesetzt. Häufige Fehlergründe:

Fehler	Beschreibung
`Email is required`	Das Feld `email` fehlt oder ist leer
`Invalid email format`	Die E-Mail-Adresse ist syntaktisch ungültig
`Email already exists in this tenant`	Ein Benutzer mit dieser E-Mail existiert bereits
`Role 'X' does not exist`	Der angegebene Rollenname wurde nicht gefunden
`Password does not meet minimum length requirement`	Passwort ist kürzer als das konfigurierte Minimum des Tenants
`Password does not meet complexity requirements`	Passwort erfüllt nicht die Anforderungen für Groß-/Kleinbuchstaben/Zahlen/Sonderzeichen

Benutzer exportieren

Export auslösen

POST/api/users/exportRequires: manage:users

Einen Export aller Benutzer im Tenant auslösen. Der Export läuft asynchron — frage den Export-Job-Status oder den Listen-Endpunkt ab, um zu erfahren, wann die Datei zum Download bereit ist.

Anforderungs-Body


{
  "format": "csv"
}

Feld	Typ	Erforderlich	Beschreibung
`format`	string	Ja	Ausgabeformat: `csv` oder `json`

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "exp_abc123",
    "format": "csv",
    "status": "PENDING",
    "totalUsers": 0,
    "createdAt": "2025-02-18T11:00:00Z",
    "expiresAt": "2025-02-19T11:00:00Z"
  }
}

Passwörter werden niemals in Exporten enthalten. Passwort-Hashes sind nicht umkehrbar und werden aus Sicherheitsgründen ausgeschlossen. Exportierte Benutzer, die in einen anderen Tenant importiert werden, müssen neue Passwörter setzen.

Export-Jobs auflisten

GET/api/users/exportRequires: manage:users

Alle Export-Jobs für den Tenant auflisten. Jobs sind nach Erstellungsdatum absteigend sortiert.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20, max: 100)

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "exp_abc123",
        "format": "csv",
        "status": "COMPLETED",
        "totalUsers": 342,
        "createdAt": "2025-02-18T11:00:00Z",
        "expiresAt": "2025-02-19T11:00:00Z"
      },
      {
        "id": "exp_def456",
        "format": "json",
        "status": "COMPLETED",
        "totalUsers": 342,
        "createdAt": "2025-02-15T09:00:00Z",
        "expiresAt": "2025-02-16T09:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "totalPages": 1
    }
  }
}

Export-Datei herunterladen

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

Die generierte Export-Datei herunterladen. Gibt eine binäre Antwort mit entsprechenden Content-Type- und Content-Disposition-Headern zurück. Die Datei ist 24 Stunden nach Abschluss des Exports verfügbar.

Antwort-Header


Content-Type: text/csv (oder application/json)
Content-Disposition: attachment; filename="benutzer-export-2025-02-18.csv"

Der Antwort-Body ist der rohe Dateiinhalt (CSV oder JSON), nicht eingebettet in den Standard-{ ok, data }-Umschlag.

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	Export-Job existiert nicht
`NOT_READY`	400	Export wird noch verarbeitet (Status ist `PENDING`)
`EXPIRED`	410	Export-Datei ist abgelaufen und wurde gelöscht (nach 24-Stunden-Fenster)

Verlauf des Export-Status

Status	Beschreibung
`PENDING`	Export-Job erstellt, Dateigenerierung läuft
`COMPLETED`	Datei generiert und zum Download bereit
`FAILED`	Dateigenerierung fehlgeschlagen (Systemfehler)

Exportierte Felder

Die Export-Datei enthält die folgenden Felder für jeden Benutzer:

Feld	CSV-Spalte	JSON-Schlüssel	Beschreibung
E-Mail	`email`	`email`	E-Mail-Adresse des Benutzers
Vorname	`firstName`	`firstName`	Vorname des Benutzers
Nachname	`lastName`	`lastName`	Nachname des Benutzers
Rollen	`roles`	`roles`	Kommagetrennte Rollennamen (CSV) oder String-Array (JSON)
E-Mail verifiziert	`emailVerified`	`emailVerified`	Ob die E-Mail verifiziert wurde
Aktiviert	`isEnabled`	`isEnabled`	Ob das Konto aktiv ist
Erstellt am	`createdAt`	`createdAt`	ISO 8601-Zeitstempel der Kontoerstellung
Letzter Login	`lastLoginAt`	`lastLoginAt`	ISO 8601-Zeitstempel der letzten Anmeldung oder leer/null

CSV-Export-Beispiel


email,firstName,lastName,roles,emailVerified,isEnabled,createdAt,lastLoginAt
[email protected],Jane,Doe,"admin,editor",true,true,2024-11-01T08:00:00Z,2025-02-18T09:30:00Z
[email protected],Bob,Smith,viewer,true,true,2024-12-15T10:00:00Z,2025-02-17T14:20:00Z
[email protected],Alice,Johnson,editor,false,true,2025-02-10T12:00:00Z,
[email protected],Carol,Williams,,true,false,2025-01-20T09:00:00Z,2025-01-25T11:00:00Z

JSON-Export-Beispiel


[
  {
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "roles": ["admin", "editor"],
    "emailVerified": true,
    "isEnabled": true,
    "createdAt": "2024-11-01T08:00:00Z",
    "lastLoginAt": "2025-02-18T09:30:00Z"
  },
  {
    "email": "[email protected]",
    "firstName": "Bob",
    "lastName": "Smith",
    "roles": ["viewer"],
    "emailVerified": true,
    "isEnabled": true,
    "createdAt": "2024-12-15T10:00:00Z",
    "lastLoginAt": "2025-02-17T14:20:00Z"
  }
]

Export-Dateien laufen nach 24 Stunden ab und werden dauerhaft gelöscht. Lade die Datei umgehend nach Abschluss der Generierung herunter. Du kannst jederzeit einen neuen Export auslösen, wenn nötig.

Migrations-Workflow

Eine typische Tenant-zu-Tenant-Migration folgt diesem Muster:

Benutzer aus dem Quell-Tenant über POST /api/users/export mit Format json exportieren.
Die Export-Datei über GET /api/users/export/[id]/download herunterladen.
Optional die Datei bearbeiten, um Rollen anzupassen oder Benutzer zu entfernen.
Die Datei in den Ziel-Tenant über POST /api/users/import importieren.
Den Import-Job über GET /api/users/import/[id] überwachen, bis der Status COMPLETED oder PARTIAL ist.
Fehler auf Zeilenebene im errors-Array überprüfen.
Importierte Benutzer benachrichtigen, ihr Passwort über Magic Link oder Passwort-Zurücksetzen zu setzen (da Passwörter nicht exportiert werden).

Berechtigungsreferenz

Berechtigung	Beschreibung
`manage:users`	Import-Dateien hochladen, Exporte auslösen, Export-Dateien herunterladen und Job-Historie anzeigen

Import- und Exportvorgänge werden im Audit-Protokoll mit den Ereignistypen user_import.created und user_export.created aufgezeichnet, einschließlich Dateiname, Format, Zeilenanzahlen und des Administrators, der den Vorgang initiiert hat.

Benutzerimport & -export API

Benutzer importieren

Import-Datei hochladen

Import-Jobs auflisten

Import-Job-Details abrufen

Verlauf des Import-Status

Import-Dateiformate

CSV-Format

JSON-Format

Feldreferenz

Fehlerbehandlung pro Zeile

Benutzer exportieren

Export auslösen

Export-Jobs auflisten

Export-Datei herunterladen

Verlauf des Export-Status

Exportierte Felder

Migrations-Workflow

Berechtigungsreferenz

Verwandte Themen