Actualizar un rol del entorno

PATCH /v1/roles/{role_id} · permiso roles:write

Actualiza el rol con un JSON merge patch (RFC 7396, Content-Type: application/merge-patch+json). If-Match es obligatorio. key no puede cambiar. Cuando un rol pasa a ser privilegiado, las asignaciones de grupos externos que apuntan a él permanecen sin aprobar y no conceden nada hasta que se aprueban con :approve. Un patch que no cambia nada conserva la versión. La escritura se registra en la auditoría como role.updated.

Solicitud

Campo Tipo Obligatorio Descripción
role_id path sí ID del rol (rol_…).
If-Match header sí ETag actual del rol.
name string no Nombre para mostrar, hasta 128 caracteres.
description string no Hasta 1024 caracteres.
is_privileged boolean no Indicador de privilegio.
assignable_in_self_service boolean no Si el rol puede asignarse en autoservicio.

Respuesta

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

Errores

HTTP code Cuándo
400 unknown_field El patch contiene un campo que no se puede escribir (por ejemplo key).
404 not_found El rol no existe en este ámbito.
412 precondition_failed If-Match no coincide con la versión actual.
422 validation_failed Un campo no es válido.
428 precondition_required Falta If-Match.
401 unauthenticated La credencial falta, no es válida o está 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 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"}'