# 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](/docs/api/fapi/front-api-token)). 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](/docs/api/fapi/organizations/memberships/list)) 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

```bash
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"]}'
```

```json
{
  "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](/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).