# Eine Organisationsrolle aktualisieren

`PATCH /fapi/v1/organizations/{org_id}/roles/{role_id}` · wird vom Anmeldehost der Umgebung aufgerufen

Ändert den Namen oder die Beschreibung einer Organisationsrolle (JSON Merge Patch, RFC 7396). Umgebungsrollen können hier nicht geändert werden. Erfordert das Cookie `__Host-idp_session` des angemeldeten 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-Proof; 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`, sodass 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 im zugehörigen Tarif enthalten sein.

## Anfrage

Header:

| Header | Pflicht | Beschreibung |
| --- | --- | --- |
| `Idp-Client` | ja | SDK-Kennung. |
| `Origin` | ja | Muss genau `https://<Anmeldehost>` sein. |
| `Content-Type` | bei einem Body | `application/json` oder `application/merge-patch+json`. |
| `If-Match` | nein | `"<version>"` der Rolle, wie zuletzt gelesen; wurde die Rolle seitdem geändert, wird `412 precondition_failed` zurückgegeben und nichts geändert. |

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

Body (mindestens ein Feld):

| Feld | Pflicht | Beschreibung |
| --- | --- | --- |
| `name` | nein | Neuer Anzeigename. |
| `description` | nein | Neue Beschreibung. |

## 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 hat `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 gewährt eine Berechtigung, die der Benutzer nicht besitzt, oder die eigene Mitgliedschaft des Benutzers enthält sie. |
| 404 | `not_found` | Keine solche Organisation oder Organisationsrolle für diesen Benutzer; eine Umgebungsrolle, eine unbekannte, fehlerhafte oder fremde ID führen zur selben Antwort. |
| 409 | `organization_pending_deletion` | Die Organisation ist zur Löschung vorgesehen. |
| 412 | `precondition_failed` | `If-Match` nennt nicht die aktuelle Version, oder die Rolle wurde während der Verarbeitung der Anfrage geändert. |
| 422 | `validation_failed` | Ein Feld ist ungültig, oder der Patch ist leer (`empty_patch`). |
| 503 | `service_unavailable` | Vorübergehend nicht verfügbar; erneut versuchen nach `Retry-After`. |

## Beispiel

```bash
curl -X PATCH https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -b cookies.txt \
  -d '{"name":"Auditors"}'
```