Umgebungsrolle aktualisieren

PATCH /v1/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. Wird eine Rolle privilegiert, bleiben die externen Gruppenzuordnungen, die auf sie zeigen, unbestätigt und gewähren nichts, bis sie mit :approve genehmigt werden. Ein Patch, der nichts ändert, behält die Version bei. Der Schreibvorgang wird als role.updated protokolliert.

Anfrage

Feld Typ Pflicht Beschreibung
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.
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": null,
  "key": "support",
  "name": "Support 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/roles/rol_01j9xr7s1t2w6x8y0z2a4b6c8e" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H 'If-Match: "1"' \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"name":"Support team"}'