# flow2act · Nutzer einladen

Lade eine Person mit Login, Organisationsrolle und optionalen Freigabegruppen ein.

Nutze einen Live-Administrator-Token, einen Sandbox-Administrator-/Entwickler-Token oder einen Servicekonto-Schlüssel mit users:invite. Service-Schlüssel dürfen nur requester-Mitglieder ohne approvalGroupIds einladen. Admin-Einladungen und Freigabegruppen erfordern den Administrator-Token. In der Sandbox erzeugt derselbe Aufruf eine simulierte Einladung (delivery=simulated), ohne E-Mail oder echtes Konto. POST /v1/sandbox/invitations/{id}/accept simuliert die erste Anmeldung und verknüpft personId mit einer reinen Sandbox-Identität. Neue flow2act-Konten erhalten ein temporäres Passwort per E-Mail und müssen beim ersten Login ein eigenes festlegen. Bestehende geeignete Konten behalten ihr Passwort und treten bei erneuter Anmeldung bei; informiere die Person direkt. flow2act liefert keine Passwörter.

Die API prüft vor Anlage und Wiederholung jeder Einladung den aktiven Workspace-Zugang sowie Administratorrechte des Nutzers oder den Servicekonto-Scope users:invite. role bezeichnet die eingeladene Person, nicht den Aufrufenden: role=admin erteilt keine Berechtigung für die Anfrage. Fehlende/ungültige Access-Tokens liefern 401; Nicht-Admin-User-Tokens, inaktive oder fremde Mitgliedschaften, Schlüssel ohne users:invite und privilegierte Service-Einladungen 403. Einladungen gelten 7 Tage. Mitgliedschaft und direkte Freigabegruppen werden erst für das passende authentifizierte Subject aktiviert. Standardrolle ist requester; admin muss ausdrücklich gewählt werden. Verzeichnisprofile bleiben separat bearbeitbar. Wiederhole nach unklarem Ergebnis denselben Idempotency-Key mit identischen Daten.

Servicekonten benötigen users:invite und dürfen nur Einladungen desselben Servicekontos auflisten/wiederholen, auch nach einer Schlüsselrotation. Admin-Einladungen, Freigabegruppen und Zugangsdaten-Delegation sind ausgeschlossen. Live-Einladungen erstellen echte Konten; Sandbox-Einladungen simulieren Einrichtung und Annahme ohne E-Mail-Versand.

## POST /v1/organization/invitations

Authentication: restricted integration key (scope: users:invite) or flow2act sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator oder Sandbox-Entwickler erforderlich. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- locale (string, optional): max length 35
- displayName (string, required): min length 1 · max length 120
- email (string, required): email · max length 128
- role (string, optional): requester | admin · default "requester"
- approvalGroupIds (array, optional): max items 50 · default []

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flow2act.com/v1/organization/invitations" \
  -H "authorization: Bearer $FLOW2ACT_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-invite-user-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "displayName": "Alex Example",
  "email": "alex@example.com",
  "role": "requester",
  "approvalGroupIds": []
}'
```

## Response excerpt

```json
{
  "status": "invited",
  "delivery": "temporary_password"
}
```

Source: /docs/invite-user
Full schemas: /docs/openapi.json