Rollen einer Mitgliedschaft ersetzen

PUT /v1/organizations/{org_id}/memberships/{membership_id}/roles · Berechtigung organizations:write

Ersetzt die manuell zugewiesenen Rollen der Mitgliedschaft durch role_ids (ein leeres Array entfernt sie alle). Rollen, die durch IdP-Zuordnungen oder Verzeichnisquellen vergeben wurden, werden nicht geändert. Wenn role_version angegeben ist, muss es der aktuellen version der Mitgliedschaft entsprechen, andernfalls 409 conflict. Die Admin-Rolle des letzten Admins kann nicht entfernt werden. Der Schreibvorgang wird als organization_membership.updated protokolliert.

Anfrage

Feld Typ Pflicht Beschreibung
org_id path ja Organisations-ID (org_…).
membership_id path ja Mitgliedschafts-ID (mem_…).
role_ids string[] ja Die vollständige Menge der Rollen-IDs (rol_…), höchstens 50.
role_version integer nein Erwartete version der Mitgliedschaft (1 oder größer).
revoke_sessions boolean nein Standard true. Legt fest, ob das Entfernen einer privilegierten (is_privileged) Rolle die Refresh-Token-Familien des Nutzers in diesem Organisationskontext widerruft (Plan §17.4); false schaltet dies aus. In diesem Release wird die Wahl nur in den Metadaten revoke_sessions des Audit-Eintrags organization_membership.updated festgehalten, und es wird keine Sitzung widerrufen; der Widerruf ist im Authentifizierungsdienst geplant (planned).

Antwort

200 OK mit der aktualisierten Mitgliedschaft und ihrem ETag.

{
  "id": "mem_01j9xn5p9s0t4v6w8x0y2z4a6c",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "user_id": "usr_01j9xh2k6p7q1r3s5t7v9w1x3y",
  "status": "active",
  "source": "admin_api",
  "reason": null,
  "roles": [
    {
      "role_id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
      "source": "admin_api",
      "assigned_at": "2026-10-12T09:31:00.123456Z"
    }
  ],
  "expires_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z",
  "activated_at": "2026-10-12T09:31:00.123456Z",
  "suspended_at": null,
  "removed_at": null,
  "updated_at": "2026-10-12T09:31:00.123456Z",
  "version": 2
}

Fehler

HTTP code Wann
404 not_found Die Mitgliedschaft existiert in dieser Organisation nicht.
403 role_not_assignable Eine Rolle ist weder eine Umgebungsrolle noch eine Rolle dieser Organisation.
409 conflict role_version stimmt nicht mit der aktuellen Version der Mitgliedschaft überein.
409 last_org_admin Die Änderung würde die Organisation ohne aktiven Admin zurücklassen.
422 validation_failed role_ids fehlt oder ist ungültig, oder role_version ist kleiner als 1.
401 unauthenticated Die Anmeldedaten fehlen, sind ungültig oder widerrufen.
403 insufficient_permissions Den Anmeldedaten fehlt die erforderliche Berechtigung. Die Zuweisung einer privilegierten (is_privileged) Rolle erfordert außerdem roles:write; ohne diese Berechtigung wird nichts geschrieben, und required_permissions nennt beide Berechtigungen.
429 rate_limited Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Wartezeit aus Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Wartezeit aus Retry-After.

Beispiel

curl -i -X PUT "https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/memberships/mem_01j9xn5p9s0t4v6w8x0y2z4a6c/roles" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_ids":["rol_01j9xr7s1t2w6x8y0z2a4b6c8e","rol_01j9xs8t2v3x7y9z1a3b5c7d9f"],"role_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. Übermitteln Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).