Reemplazar los permisos de un rol del entorno

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

Reemplaza el conjunto de permisos del rol por permission_ids (el conjunto completo; un array vacío elimina todos los permisos; el orden no importa). Un rol del entorno puede tener como máximo 500 permisos. El rol que las organizaciones usan como rol de administrador debe conservar todos los permisos del sistema (permission_reserved). If-Match es opcional; si se envía, debe coincidir con el ETag actual. Volver a escribir el mismo conjunto no cambia nada y mantiene la versión. El cambio se registra en la auditoría como role.updated con change=permissions, y los tokens emitidos después llevan los nuevos permisos.

Solicitud

Campo Tipo Obligatorio Descripción
role_id path sí ID del rol (rol_…).
If-Match header no ETag actual; 412 si no coincide.
permission_ids string[] sí El conjunto completo de IDs de permiso (perm_…), como máximo 500.

Respuesta

200 OK con el rol y su 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
}

Errores

HTTP code Cuándo
404 not_found El rol no existe en este entorno.
412 precondition_failed If-Match no coincide con la versión actual.
422 permission_reserved El rol es el rol de administrador de la organización y el conjunto elimina un permiso del sistema.
422 validation_failed permission_ids falta, tiene un ID con formato incorrecto o desconocido (unknown_permission), un duplicado o más de 500 elementos.
401 unauthenticated La credencial falta, no es válida o fue revocada.
403 insufficient_permissions La credencial no tiene el permiso requerido.
429 rate_limited Se superó el límite de frecuencia; reintente después del período indicado en Retry-After.
503 service_unavailable Una dependencia no está disponible temporalmente; reintente después del período indicado en Retry-After.

Ejemplo

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