Rollen eines Mitglieds festlegen

PUT /fapi/v1/organizations/{org_id}/memberships/{membership_id}/roles · aufgerufen vom Anmeldehost der Umgebung

Ersetzt die Rollen einer Mitgliedschaft durch eine vollständige Menge, für eine Profilansicht der Organisation. Die Menge umfasst nur die Rollen, die Sie in dieser Organisation sehen können: ihre eigenen Rollen und die Umgebungsrollen, die Organisations-Admins offenstehen. Die übrigen Rollen des Mitglieds bleiben erhalten. Eine leere Menge entfernt alle Rollen, die Sie sehen können; hat das Mitglied danach keine Rolle mehr, wird ihm die Standardrolle der Organisation zugewiesen.

Erfordert das Cookie __Host-idp_session des authentifizierten Benutzers mit exaktem Origin oder ein Front-API-Zugriffstoken einer Erstanbieter-Anwendung (Authorization: DPoP <token> mit einem DPoP-Nachweis; siehe Front-API-Zugriffstoken). Der Benutzer muss aktives Mitglied der Organisation mit der Berechtigung idp_members:update_roles sein. Ein Benutzer, der kein Mitglied ist, erhält 404 not_found; ein Mitglied ohne die Berechtigung erhält 403 insufficient_permissions.

Zuweisungsregeln:

Jede Berechtigung jeder zugewiesenen Rolle muss eine sein, die Sie selbst besitzen.
Nur ein Mitglied mit der Admin-Rolle kann eine privilegierte Rolle zuweisen.
Sie können Ihre eigenen Rollen nicht ändern.
Der letzte aktive Admin kann die Admin-Rolle nicht verlieren (409 last_org_admin).

Mit @keenauth/js: await keenauth.organizations.setMemberRoles(orgId, membershipId, [roleId], { expectedVersion: 3 }).

Anfrage

Header:

Header	Pflicht	Beschreibung
`Idp-Client`	ja	SDK-Kennung.
`Origin`	ja, mit dem Cookie	`https://<Anmeldehost>`.
`If-Match`	nein	Eine Version, `"<version>"`, aus der Mitgliederliste. Eine nicht passende Version oder mehr als eine Version liefert `412 precondition_failed`.

org_id: Kennung der Organisation (org_…). membership_id: Kennung der Mitgliedschaft (mem_…).

Body: {"role_ids": ["rol_…"]}, höchstens 50 Rollen. role_ids ist erforderlich; [] ist eine gültige Menge.

Antwort

200 OK mit der Mitgliedschaft (dieselben Felder wie ein Eintrag in der Mitgliederliste) und ETag: "<version>".

Fehler

Status	Code	Wann
400	`malformed_request`	`If-Match` ist fehlerhaft.
400	`unknown_field`	Der Body enthält ein anderes Feld als `role_ids`.
401	`unauthenticated`	Kein gültiges Sitzungs-Cookie oder Token.
403	`insufficient_permissions`	Dem Benutzer fehlt `idp_members:update_roles` in der Organisation.
403	`role_not_assignable`	Eine der obigen Zuweisungsregeln verweigert die Änderung.
403	`origin_not_allowed`	Das `Origin` stimmt nicht überein.
404	`not_found`	Keine solche Organisation, Mitgliedschaft oder Rolle für diesen Benutzer; eine unbekannte, fehlerhafte oder fremde Kennung führt zur gleichen Antwort.
409	`last_org_admin`	Die Änderung würde die Organisation ohne aktiven Admin zurücklassen.
409	`role_limit_reached`	Das Mitglied würde mehr als 50 Rollen halten.
409	`organization_disabled`	Die Organisation ist deaktiviert oder zur Löschung vorgemerkt (`organization_pending_deletion`).
412	`precondition_failed`	`If-Match` nennt nicht die aktuelle Version der Mitgliedschaft.
422	`validation_failed`	`role_ids` fehlt, ist zu lang oder enthält eine fehlerhafte Kennung.
503	`service_unavailable`	Vorübergehend nicht verfügbar; nach `Retry-After` erneut versuchen.

Beispiel

curl -X PUT "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/memberships/mem_01jbz6x8kq3m2n4p5r6s7t8v9b/roles" \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "3"' \
  -b cookies.txt \
  -d '{"role_ids":["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"]}'

{
  "id": "mem_01jbz6x8kq3m2n4p5r6s7t8v9b",
  "user_id": "usr_01jbz6x8kq3m2n4p5r6s7t8v9c",
  "status": "active",
  "roles": [{ "role_id": "rol_01jbz6x8kq3m2n4p5r6s7t8v9w", "source": "admin_api" }],
  "created_at": "2026-11-03T09:00:00Z",
  "activated_at": "2026-11-03T09:00:00Z",
  "expires_at": null,
  "updated_at": "2026-11-03T10:00:00Z",
  "version": 4
}

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