# Mitglied einladen

`POST /fapi/v1/organizations/{org_id}/invitations` · aufgerufen vom Anmeldehost der Umgebung

Lädt eine E-Mail-Adresse in die Organisation ein. KeenAuth versendet die Einladungs-E-Mail; das Einladungstoken und der Annahme-Link werden Ihnen nie zurückgegeben. Existiert bereits eine ausstehende Einladung für dieselbe Adresse mit denselben Rollen, wird sie erneut gesendet und die Antwort lautet `200 OK`; eine neue Einladung ergibt `201 Created`.

Erforderlich ist das Cookie `__Host-idp_session` des authentifizierten Benutzers mit einem exakten `Origin` oder das Front-API-Zugriffstoken einer First-Party-App (`Authorization: DPoP <token>` mit einem DPoP-Proof; siehe [Front-API-Zugriffstoken](/docs/api/fapi/front-api-token)). Der Benutzer muss ein aktives Mitglied der Organisation sein und die Berechtigung `idp_members:invite` besitzen. Ein Benutzer, der kein Mitglied ist, erhält `404 not_found`; ein Mitglied ohne die Berechtigung erhält `403 insufficient_permissions`. Nur ein Mitglied mit der Administratorrolle kann mit einer privilegierten Rolle einladen (`403 role_not_assignable`).

Mit `@keenauth/js`: `const { invitation, resent } = await keenauth.organizations.invite(orgId, { email, roleIds: [roleId] })`.

## Anfrage

Header:

| Header | Erforderlich | Beschreibung |
| --- | --- | --- |
| `Idp-Client` | ja | SDK-Kennung. |
| `Origin` | ja, mit dem Cookie | `https://<Anmeldehost>`. |

`org_id`: die Kennung der Organisation (`org_…`).

Body:

| Feld | Erforderlich | Beschreibung |
| --- | --- | --- |
| `email` | ja | Die einzuladende Adresse, höchstens 254 Zeichen. |
| `role_ids` | nein | Höchstens 10 Rollen (`rol_…`); ohne Angabe gilt die Standardrolle der Organisation. |
| `ttl_days` | nein | Wie lange die Einladung gültig bleibt, 1–30 Tage; ohne Angabe der Standardwert der Umgebung. |

## Antwort

`201 Created` mit `Location` und `ETag`, oder `200 OK`, wenn eine ausstehende Einladung erneut gesendet wurde. Der Body ist die Einladung:

`id` (`inv_…`), `email` (nur solange ausstehend, sonst `null`), `role_ids`, `delivery`, `delivery_status` (`queued`, `sent`, `bounced` oder `not_sent`), `status` (`pending`, `accepted`, `revoked` oder `expired`), `send_count`, `last_sent_at`, `expires_at`, `accepted_user_id`, `accepted_at`, `revoked_at`, `created_at`, `updated_at`, `version`.

## Fehler

| Status | Code | Wann |
| --- | --- | --- |
| 400 | `unknown_field` | Der Body enthält ein Feld, das oben nicht aufgeführt ist. |
| 401 | `unauthenticated` | Kein gültiges Sitzungs-Cookie oder Token. |
| 403 | `insufficient_permissions` | Der Benutzer hat in der Organisation nicht `idp_members:invite`. |
| 403 | `role_not_assignable` | Eine Rolle ist privilegiert und der Benutzer hat nicht die Administratorrolle. |
| 403 | `origin_not_allowed` | Der `Origin` passt nicht. |
| 404 | `not_found` | Für diesen Benutzer existiert keine solche Organisation oder Rolle. |
| 409 | `invitation_already_pending` | Für diese Adresse existiert eine ausstehende Einladung mit anderen Rollen. |
| 409 | `membership_already_exists` | Die Adresse gehört bereits einem Mitglied der Organisation. |
| 409 | `organization_membership_limit_reached` | Die Organisation hat ihre Mitgliederobergrenze erreicht. |
| 409 | `organization_disabled` | Die Organisation ist deaktiviert oder zur Löschung vorgemerkt (`organization_pending_deletion`). |
| 422 | `validation_failed` | `email`, `role_ids` oder `ttl_days` fehlt oder ist ungültig. |
| 429 | `invite_rate_limited` | Zu viele Einladungen oder erneute Sendungen; wiederholen Sie die Anfrage nach `Retry-After`. |
| 501 | `not_implemented` | Der Versand von Einladungs-E-Mails ist in dieser Umgebung nicht eingerichtet. |
| 503 | `service_unavailable` | Vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach `Retry-After`. |

## Beispiel

```bash
curl -X POST "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/invitations" \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"email":"new.member@example.com","role_ids":["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],"ttl_days":7}'
```

```json
{
  "id": "inv_01jbz6x8kq3m2n4p5r6s7t8v9d",
  "email": "new.member@example.com",
  "role_ids": ["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],
  "delivery": "email",
  "delivery_status": "queued",
  "status": "pending",
  "send_count": 1,
  "last_sent_at": "2026-11-03T10:00:00Z",
  "expires_at": "2026-11-10T10:00:00Z",
  "accepted_user_id": null,
  "accepted_at": null,
  "revoked_at": null,
  "created_at": "2026-11-03T10:00:00Z",
  "updated_at": "2026-11-03T10:00:00Z",
  "version": 1
}
```

## Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Organisationsmitgliedschaften und Einladungen. [Personenbezogene Daten in den KeenAuth-APIs](/docs/policies/personal-data) beschreibt, was gespeichert wird, wie lange es aufbewahrt wird und wie es gelöscht wird. Senden Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).