Einladungen gesammelt erstellen

POST /v1/invitations:batch · Berechtigung invitations:write

Erstellt 1 bis 100 Einladungen (items). Jedes Element folgt den Regeln von POST /v1/invitations und wird eigenständig geschrieben: Ein fehlschlagendes Element hält die anderen nicht auf. Die Antwort ist 200 OK, und items behält die Reihenfolge der Anfrage bei. Der status eines Elements ist 201 (neue Einladung), 200 (eine ausstehende Einladung wurde erneut gesendet) oder der HTTP-Status seines Fehlers. Ein fehlgeschlagenes Element enthält error mit code, status und Feldzeigern der Form /items/<i>/…. Die accept_url von link_only-Elementen wird nur in dieser Antwort zurückgegeben (Cache-Control: no-store); eine mit Idempotency-Key wiederholte Antwort enthält keine Links und liefert secret_redacted: true. Ein Element ohne organization_id ist eine Umgebungseinladung. Ein email-Element wird per E-Mail versendet; ist der E-Mail-Versand für Einladungen in der Bereitstellung nicht konfiguriert, ist es ein Elementfehler 501 not_implemented, und eine application_id, die in dieser Umgebung nicht existiert, ist ein Elementfehler 404 not_found. Jede geschriebene Einladung wird als invitation.created protokolliert.

Anfrage

Feld Typ Pflicht Beschreibung
items object[] ja 1 bis 100 Einladungen, jeweils mit den Feldern von POST /v1/invitations.
Idempotency-Key header nein Sorgt dafür, dass ein erneuter Versuch das gespeicherte Ergebnis ohne Links zurückgibt.

Antwort

200 OK mit einem Ergebnis pro Element.

{
  "items": [
    {
      "status": 201,
      "invitation": {
        "id": "inv_01j9xt9v3w4y8z0a2b4c6d8e0g",
        "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
        "email": "ada@example.com",
        "role_ids": [
          "rol_01j9xr7s1t2w6x8y0z2a4b6c8e"
        ],
        "application_id": null,
        "delivery": "link_only",
        "delivery_status": "not_sent",
        "status": "pending",
        "send_count": 1,
        "last_sent_at": "2026-10-12T09:31:00.123456Z",
        "expires_at": "2026-10-19T09:31:00.123456Z",
        "accepted_user_id": null,
        "accepted_at": null,
        "revoked_at": null,
        "created_at": "2026-10-12T09:31:00.123456Z",
        "updated_at": "2026-10-12T09:31:00.123456Z",
        "version": 1,
        "accept_url": "https://acme.eu.keenauth.app/u/login?invitation=<token>"
      }
    },
    {
      "status": 422,
      "error": {
        "code": "validation_failed",
        "status": 422,
        "errors": [
          {
            "pointer": "/items/1/email",
            "code": "invalid_value"
          }
        ]
      }
    }
  ]
}

Fehler

HTTP code Wann
422 validation_failed items fehlt, ist leer oder enthält mehr als 100 Einträge.
401 unauthenticated Die Anmeldeinformationen fehlen, sind ungültig oder wurden widerrufen.
403 insufficient_permissions Die Anmeldeinformationen haben nicht die erforderliche Berechtigung. Ein Element mit einer privilegierten Rolle (is_privileged) schlägt mit diesem Elementfehler fehl, wenn die Anmeldeinformationen keine Berechtigung roles:write haben.
429 rate_limited Das Ratenlimit wurde überschritten; versuchen Sie es nach Ablauf von Retry-After erneut.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es nach Ablauf von Retry-After erneut.

Beispiel

curl -i -X POST "https://api.eu.keenauth.com/v1/invitations:batch" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f6c1d2e3a4b5c6d7e8f9a0b" \
  -d '{"items":[{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","email":"ada@example.com","delivery":"link_only"},{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","email":"bob@example.com","delivery":"link_only"}]}'

Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Organisationszugehörigkeiten 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).