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

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

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"}'