Organisationsrolle aktualisieren

PATCH /v1/organizations/{org_id}/roles/{role_id} · Berechtigung roles:write

Aktualisiert die Rolle mit einem JSON Merge Patch (RFC 7396, Content-Type: application/merge-patch+json). If-Match ist erforderlich. key kann sich nicht ändern. Eine Organisationsrolle kann nicht privilegiert werden. Ein Patch, der nichts ändert, behält die Version bei. Der Schreibvorgang wird als role.updated protokolliert.

Anfrage

Feld Typ Pflicht Beschreibung
org_id path ja Organisations-ID (org_…).
role_id path ja Rollen-ID (rol_…).
If-Match header ja Aktuelles ETag der Rolle.
name string nein Anzeigename, bis zu 128 Zeichen.
description string nein Bis zu 1024 Zeichen.
is_privileged boolean nein Kennzeichen für privilegierte Rollen (muss false bleiben).
assignable_in_self_service boolean nein Ob die Rolle im Self-Service zugewiesen werden kann.

Antwort

200 OK mit der Rolle und ihrem neuen ETag.

{
  "id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "key": "billing-admin",
  "name": "Billing admin team",
  "description": "",
  "is_privileged": false,
  "assignable_in_self_service": true,
  "permission_ids": [],
  "created_at": "2026-10-12T09:31:00.123456Z",
  "updated_at": "2026-10-12T10:00:00Z",
  "version": 2
}

Fehler

HTTP code Wann
400 unknown_field Der Patch enthält ein Feld, das nicht geschrieben werden kann (zum Beispiel key).
404 not_found Die Rolle existiert in diesem Geltungsbereich nicht.
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version überein.
422 validation_failed Ein Feld ist ungültig.
428 precondition_required If-Match fehlt.
401 unauthenticated Die Anmeldeinformation fehlt, ist ungültig oder widerrufen.
403 insufficient_permissions Die Anmeldeinformation hat nicht die erforderliche Berechtigung.
429 rate_limited Das Ratenlimit wurde überschritten; nach der Dauer von Retry-After erneut versuchen.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; nach der Dauer von Retry-After erneut versuchen.

Beispiel

curl -i -X PATCH "https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/roles/rol_01j9xr7s1t2w6x8y0z2a4b6c8e" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H 'If-Match: "1"' \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"name":"Billing admin team"}'