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). 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

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}'

{
  "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 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).