# Berechtigungen einer Rolle festlegen

`PUT /fapi/v1/organizations/{org_id}/roles/{role_id}/permissions` · wird vom Anmelde-Host der Umgebung aufgerufen

Ersetzt die Berechtigungsmenge einer Organisationsrolle. Es können nur Berechtigungen verwendet werden, die die Umgebung für Organisationsrollen zulässt, und Administratoren können nur Berechtigungen gewähren, die sie selbst besitzen. Berechtigungen und APIs können hier nicht angelegt werden. Erforderlich ist das Cookie `__Host-idp_session` des authentifizierten Benutzers; fehlt das Cookie, ist es abgelaufen oder widerrufen, wird `401 unauthenticated` zurückgegeben. Eine Erstanbieter-Anwendung auf einem anderen Ursprung kann stattdessen ihr Front-API-Zugriffstoken senden (`Authorization: DPoP <token>` mit einem DPoP-Nachweis; siehe [Front-API-Zugriffstoken](/docs/api/fapi/front-api-token)). Der Benutzer muss aktives Mitglied der Organisation sein und die Berechtigung `idp_roles:manage` besitzen. Ein Benutzer, der kein Mitglied ist, erhält `404 not_found`, damit die Existenz der Organisation nicht offengelegt wird; ein Mitglied ohne die Berechtigung erhält `403 insufficient_permissions`. Organisationsrollen müssen für die Umgebung aktiviert und in deren Tarif enthalten sein.

## Anfrage

Header:

| Header | Erforderlich | Beschreibung |
| --- | --- | --- |
| `Idp-Client` | ja | SDK-Kennung. |
| `Origin` | ja | Muss exakt `https://<sign-in host>` sein. |
| `Content-Type` | mit Body | `application/json`. |
| `If-Match` | nein | `"<version>"` der Rolle, wie zuletzt gelesen; wurde die Rolle seitdem geändert, wird `412 precondition_failed` zurückgegeben und nichts ändert sich. |

`org_id`: die Organisations-ID (`org_…`). `role_id`: die Rollen-ID (`rol_…`).

Body:

| Feld | Erforderlich | Beschreibung |
| --- | --- | --- |
| `permission_ids` | ja | Die vollständige Menge, höchstens 100 Berechtigungs-IDs (`perm_…`); `[]` entfernt alle. |

## Antwort

`200 OK` mit einem neuen `ETag`; der Body ist die Rolle (siehe [Eine Organisationsrolle abrufen](./get)).

## Fehler

| Status | Code | Wann |
| --- | --- | --- |
| 401 | `unauthenticated` | Kein gültiges Sitzungs-Cookie. |
| 403 | `origin_not_allowed` | `Origin` fehlt oder ist falsch. |
| 403 | `insufficient_permissions` | Der Benutzer besitzt `idp_roles:manage` in der Organisation nicht. |
| 403 | `plan_feature_unavailable` | Der Tarif der Umgebung enthält keine Organisationsrollen (`feature`, `required_plan`). |
| 403 | `org_custom_roles_disabled` | Organisationsrollen sind für die Umgebung deaktiviert. |
| 403 | `role_not_assignable` | Die Rolle oder die neue Menge gewährt eine Berechtigung, die der Benutzer nicht besitzt, oder die eigene Mitgliedschaft des Benutzers trägt die Rolle. |
| 404 | `not_found` | Für diesen Benutzer existiert keine solche Organisation oder Organisationsrolle; eine Umgebungsrolle, eine unbekannte, fehlerhafte oder fremde ID führt zur selben Antwort. |
| 409 | `organization_pending_deletion` | Die Organisation ist zur Löschung vorgemerkt. |
| 412 | `precondition_failed` | `If-Match` nennt nicht die aktuelle Version, oder die Rolle wurde während der Verarbeitung der Anfrage geändert. |
| 422 | `permission_not_allowed` | Eine Berechtigung ist für Organisationsrollen nicht zulässig. |
| 422 | `permission_reserved` | Eine Berechtigung ist der Plattform vorbehalten. |
| 422 | `validation_failed` | Die Liste ist ungültig oder zu lang. |
| 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/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w/permissions \
  -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 '{"permission_ids":["perm_01jbz6x8kq3m2n4p5r6s7t8v9b"]}'
```