Reemplazar los roles directos de un usuario

PUT /v1/users/{user_id}/roles · permiso users:write

Reemplaza los roles de entorno directos del usuario por role_ids (el conjunto completo, como máximo 50; un array vacío los elimina todos). Los roles de organización no se pueden asignar directamente; asígnalos mediante una membresía de organización. Volver a escribir el mismo conjunto no cambia nada. Un cambio marca las familias de refresh tokens del usuario con roles_changed, de modo que el siguiente refresh incluya los nuevos roles, y se audita como user.updated con change=roles. Si el conjunto contiene un rol privilegiado (is_privileged), ya sea recién añadido o conservado, la credencial también necesita roles:write; quitar un rol privilegiado del conjunto necesita solo users:write.

Solicitud

Campo Tipo Obligatorio Descripción
user_id path sí ID del usuario (usr_…).
role_ids string[] sí El conjunto completo de IDs de roles de entorno (rol_…), como máximo 50.

Respuesta

200 OK con los nuevos IDs de roles.

{
  "role_ids": [
    "rol_01j9xr7s1t2w6x8y0z2a4b6c8e"
  ]
}

Errores

HTTP code Cuándo
403 role_not_assignable Un rol es un rol de organización.
404 not_found El usuario no existe en este entorno.
422 validation_failed Falta role_ids, tiene un ID mal formado o desconocido (unknown_role), un duplicado o más de 50 elementos.
401 unauthenticated La credencial falta, no es válida o ha sido revocada.
403 insufficient_permissions La credencial no tiene el permiso requerido. Asignar un rol privilegiado (is_privileged) también requiere roles:write; sin él no se escribe nada y required_permissions enumera ambos permisos.
429 rate_limited Se superó el límite de frecuencia; reintenta después del periodo Retry-After.
503 service_unavailable Una dependencia no está disponible temporalmente; reintenta después del periodo Retry-After.

Ejemplo

curl -i -X PUT "https://api.eu.keenauth.com/v1/users/usr_01j9xh2k6p7q1r3s5t7v9w1x3y/roles" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_ids":["rol_01j9xr7s1t2w6x8y0z2a4b6c8e"]}'