# Remplacer les rôles directs d'un utilisateur

`PUT /v1/users/{user_id}/roles` · permission `users:write`

Remplace les rôles d'environnement directs de l'utilisateur par `role_ids` (l'ensemble complet, 50 au maximum ; un tableau vide les supprime tous). Les rôles d'organisation ne peuvent pas être attribués directement ; attribuez-les par l'intermédiaire d'une adhésion à l'organisation. Réécrire le même ensemble ne modifie rien. Un changement marque les familles de refresh tokens de l'utilisateur avec `roles_changed` (le prochain refresh transporte les nouveaux rôles) et est consigné dans l'audit sous `user.updated` avec `change=roles`. Si l'ensemble contient un rôle privilégié (`is_privileged`), qu'il soit nouvellement ajouté ou conservé, l'identifiant doit aussi posséder `roles:write` ; retirer un rôle privilégié de l'ensemble exige seulement `users:write`.

## Requête

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `user_id` | path | oui | Identifiant de l'utilisateur (`usr_…`). |
| `role_ids` | string[] | oui | L'ensemble complet des identifiants de rôles d'environnement (`rol_…`), 50 au maximum. |

## Réponse

`200 OK` avec les nouveaux identifiants de rôles.

```json
{
  "role_ids": [
    "rol_01j9xr7s1t2w6x8y0z2a4b6c8e"
  ]
}
```

## Erreurs

| HTTP | code | Quand |
|---|---|---|
| 403 | `role_not_assignable` | Un rôle est un rôle d'organisation. |
| 404 | `not_found` | L'utilisateur n'existe pas dans cet environnement. |
| 422 | `validation_failed` | `role_ids` est absent, contient un identifiant mal formé ou inconnu (`unknown_role`), un doublon, ou plus de 50 éléments. |
| 401 | `unauthenticated` | L'identifiant est absent, invalide ou révoqué. |
| 403 | `insufficient_permissions` | L'identifiant ne possède pas la permission requise. Attribuer un rôle privilégié (`is_privileged`) exige aussi `roles:write` ; sans elle, rien n'est écrit et `required_permissions` liste les deux permissions. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; réessayez après la période `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez après la période `Retry-After`. |

## Exemple

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