API - Benutzer Admin

📕 Für Administratoren und Entwickler

Über die spiritflow Public API können Benutzer des Mandanten programmatisch abgerufen und angelegt werden. Alle Endpunkte sind unter dem Basis-Pfad /api/v1/users erreichbar und erfordern einen gültigen API-Key mit dem entsprechenden Scope.

Benutzer auflisten

GET /api/v1/users

Erforderlicher Scope: users:read

Gibt alle aktiven Benutzer des Mandanten zurück.

Antwort-Felder:

Feld	Typ	Beschreibung
`id`	number	Eindeutige ID des Benutzers
`displayName`	string	Anzeigename
`email`	string	E-Mail-Adresse
`roles`	string[]	Rollen des Benutzers

Antwort (200 OK):

{
  "data": [
    {
      "id": 2,
      "displayName": "Max Mustermann",
      "email": "max.mustermann@firma.de",
      "roles": ["TENANT_ADMIN"]
    },
    {
      "id": 5,
      "displayName": "Lisa Schmidt",
      "email": "lisa.schmidt@firma.de",
      "roles": ["USER"]
    }
  ],
  "pagination": {
    "page": 0,
    "size": 2,
    "totalElements": 2,
    "totalPages": 1
  },
  "meta": {
    "requestId": "...",
    "timestamp": "2025-03-01T10:30:00Z"
  }
}

cURL-Beispiel:

curl "https://app.spiritflow.team/api/v1/users" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Einzelnen Benutzer abrufen

GET /api/v1/users/{id}

Erforderlicher Scope: users:read

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Benutzers

Antwort (200 OK): Identisch mit den Einträgen der Benutzerliste.

Fehler-Codes:

HTTP-Status	Code	Beschreibung
404	`NOT_FOUND`	Benutzer nicht gefunden oder gehoert nicht zu diesem Mandanten

cURL-Beispiel:

curl "https://app.spiritflow.team/api/v1/users/5" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Benutzer anlegen

POST /api/v1/users

Erforderlicher Scope: users:write

Request-Body:

Feld	Typ	Pflicht	Beschreibung
`username`	string	Ja	Benutzername (eindeutig innerhalb des Mandanten)
`email`	string	Ja	E-Mail-Adresse (systemweit eindeutig)
`firstName`	string	Ja	Vorname
`lastName`	string	Ja	Nachname
`password`	string	Ja	Passwort (wird serverseitig gehasht)
`roles`	string[]	Nein	Rollen, Standard: `["USER"]`. Erlaubt: `USER`, `TEAM_LEADER`, `PROJECT_MANAGER`, `EXTERNAL_MEMBER`, `FIELD_USER`
`employmentStartDate`	string	Nein	Beschaeftigungsbeginn (YYYY-MM-DD)
`weeklyWorkingHours`	number	Nein	Wochenstunden (überschreibt Mandanten-Standard)
`workingDays`	string[]	Nein	Arbeitstage, z.B. `["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY"]`

Antwort (201 Created): Gleiche Felder wie bei der Benutzerliste.

Fehler-Codes:

HTTP-Status	Code	Beschreibung
402	`LICENSE_SEAT_LIMIT_REACHED`	Das Lizenz-Sitzplatzlimit des Mandanten ist erreicht
409	`CONFLICT`	E-Mail-Adresse oder Benutzername bereits vergeben

cURL-Beispiel:

curl -X POST "https://app.spiritflow.team/api/v1/users" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "j.mueller",
    "email": "j.mueller@firma.de",
    "firstName": "Julia",
    "lastName": "Müller",
    "password": "sicheresPasswort123!",
    "roles": ["USER"]
  }'

Profilbild hochladen

POST /api/v1/users/{id}/avatar

Erforderlicher Scope: users:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Benutzers

Request: Multipart Form-Data mit dem Feld file. Unterstuetzte Formate: JPEG, PNG, GIF, WebP.

Antwort (200 OK):

{
  "data": {
    "url": "/api/attachments/profile-photos/abc123.jpg"
  }
}

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`BAD_REQUEST`	Dateiformat nicht unterstützt oder Datei fehlt
404	`NOT_FOUND`	Benutzer nicht gefunden

cURL-Beispiel:

curl -X POST "https://app.spiritflow.team/api/v1/users/5/avatar" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@/pfad/zum/foto.jpg"

Benutzer aktualisieren

PATCH /api/v1/users/{id}

Aktualisiert einen bestehenden Benutzer (PATCH-Semantik). Nur angegebene Felder werden geändert. null-Werte bedeuten “nicht ändern”.

Erforderlicher Scope: users:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Benutzers

Request-Body (alle Felder optional):

Feld	Typ	Beschreibung
`firstName`	String	Vorname (max. 100 Zeichen)
`lastName`	String	Nachname (max. 100 Zeichen)
`displayName`	String	Anzeigename (max. 201 Zeichen). Wird in `firstName` und `lastName` aufgeteilt, wenn diese nicht explizit angegeben sind.
`username`	String	Benutzername (eindeutig innerhalb des Mandanten, max. 100 Zeichen)
`roles`	String[]	Rollen. Erlaubt: `USER`, `TEAM_LEADER`, `PROJECT_MANAGER`, `EXTERNAL_MEMBER`, `FIELD_USER`. Nicht erlaubt: `TENANT_ADMIN`, `SUPER_ADMIN`.
`employmentStartDate`	String	Eintrittsdatum (YYYY-MM-DD)
`employmentEndDate`	String	Austrittsdatum (YYYY-MM-DD). `null` = noch beschäftigt
`weeklyWorkingHours`	number	Individuelle Wochenarbeitsstunden
`workingDays`	String[]	Arbeitstage, z.B. `["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY"]`
`defaultHourlyRate`	number	Standard-Stundensatz in Euro
`annualVacationDays`	number	Individuelle Urlaubstage pro Jahr
`jobTitle`	String	Berufsbezeichnung (max. 100 Zeichen)
`mobilePhone`	String	Mobiltelefonnummer (max. 20 Zeichen)
`enabled`	boolean	Benutzerkonto sperren. Nur `false` erlaubt (sperren). Reaktivierung archivierter Benutzer ist über die Public API nicht möglich.

Antwort (200 OK): Aktualisiertes Benutzerobjekt (gleiche Struktur wie bei der Benutzerliste)

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`VALIDATION_ERROR`	Ungültige Feldwerte oder verbotene Rolle
404	`NOT_FOUND`	Benutzer nicht gefunden
409	`CONFLICT`	Benutzername bereits vergeben

cURL-Beispiel:

curl -X PATCH "https://app.spiritflow.team/api/v1/users/7" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jobTitle": "Senior-Entwickler",
    "weeklyWorkingHours": 38.5,
    "roles": ["USER", "TEAM_LEADER"]
  }'

Benutzer deaktivieren

DELETE /api/v1/users/{id}

Deaktiviert einen Benutzer (archiviert ihn). Der Tenant-Admin kann nicht deaktiviert werden.

Erforderlicher Scope: users:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`id`	Long	ID des Benutzers

Antwort: 204 No Content

Fehler-Codes:

HTTP-Status	Code	Beschreibung
403	`ACCESS_DENIED`	Versuch, den Tenant-Admin zu deaktivieren
404	`NOT_FOUND`	Benutzer nicht gefunden oder gehört nicht zu diesem Mandanten

cURL-Beispiel:

curl -X DELETE "https://app.spiritflow.team/api/v1/users/7" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"