Berechtigungen einer Umgebungsrolle ersetzen

PUT /v1/roles/{role_id}/permissions · Berechtigung roles:write

Ersetzt den Berechtigungssatz der Rolle durch permission_ids (der vollständige Satz; ein leeres Array entfernt alle Berechtigungen; die Reihenfolge spielt keine Rolle). Eine Umgebungsrolle hält höchstens 500 Berechtigungen. Die Rolle, die Organisationen als Administratorrolle verwenden, muss alle Systemberechtigungen behalten (permission_reserved). If-Match ist optional; wenn es angegeben wird, muss es mit dem aktuellen ETag übereinstimmen. Das erneute Schreiben desselben Satzes ändert nichts und behält die Version bei. Die Änderung wird als role.updated mit change=permissions protokolliert, und nach ihr ausgestellte Tokens tragen die neuen Berechtigungen.

Anfrage

Feld Typ Pflicht Beschreibung
role_id path ja Rollen-ID (rol_…).
If-Match header nein Aktueller ETag; 412, wenn er nicht übereinstimmt.
permission_ids string[] ja Der vollständige Satz der Berechtigungs-IDs (perm_…), höchstens 500.

Antwort

200 OK mit der Rolle und ihrem ETag.

{
  "id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
  "organization_id": null,
  "key": "support",
  "name": "Support",
  "description": "",
  "is_privileged": false,
  "assignable_in_self_service": true,
  "permission_ids": [
    "perm_01j9xs0a2b4c6d8e0f2g4h6j8k",
    "perm_01j9xs0a2b4c6d8e0f2g4h6j8m"
  ],
  "created_at": "2026-10-12T09:31:00.123456Z",
  "updated_at": "2026-10-12T10:00:00Z",
  "version": 2
}

Fehler

HTTP code Wann
404 not_found Die Rolle existiert in dieser Umgebung nicht.
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version überein.
422 permission_reserved Die Rolle ist die Administratorrolle der Organisation und der Satz entfernt eine Systemberechtigung.
422 validation_failed permission_ids fehlt, enthält eine fehlerhafte oder unbekannte ID (unknown_permission), ein Duplikat oder mehr als 500 Einträge.
401 unauthenticated Der Berechtigungsnachweis fehlt, ist ungültig oder widerrufen.
403 insufficient_permissions Dem Berechtigungsnachweis fehlt die erforderliche Berechtigung.
429 rate_limited Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Zeit aus Retry-After.

Beispiel

curl -i -X PUT "https://api.eu.keenauth.com/v1/roles/rol_01j9xr7s1t2w6x8y0z2a4b6c8e/permissions" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H 'If-Match: "1"' \
  -H "Content-Type: application/json" \
  -d '{"permission_ids":["perm_01j9xs0a2b4c6d8e0f2g4h6j8k","perm_01j9xs0a2b4c6d8e0f2g4h6j8m"]}'