# Remplacer les rôles d'une appartenance

`PUT /v1/organizations/{org_id}/memberships/{membership_id}/roles` · autorisation `organizations:write`

Remplace les rôles attribués manuellement à l'appartenance par `role_ids` (un tableau vide les supprime). Les rôles accordés par les correspondances IdP ou les sources d'annuaire ne sont pas modifiés. Si `role_version` est fourni, il doit être égal à la `version` actuelle de l'appartenance, sinon `409 conflict`. Le rôle d'administrateur du dernier administrateur ne peut pas être retiré. L'écriture est journalisée sous `organization_membership.updated`.

## Requête

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `org_id` | path | oui | Identifiant de l'organisation (`org_…`). |
| `membership_id` | path | oui | Identifiant de l'appartenance (`mem_…`). |
| `role_ids` | string[] | oui | L'ensemble complet des identifiants de rôles (`rol_…`), 50 au maximum. |
| `role_version` | integer | non | Valeur `version` attendue de l'appartenance (1 ou plus). |
| `revoke_sessions` | boolean | non | Valeur par défaut `true`. Détermine si le retrait d'un rôle privilégié (`is_privileged`) révoque les familles de jetons d'actualisation de l'utilisateur dans ce contexte d'organisation (plan §17.4) ; `false` désactive cette révocation. Dans cette version, ce choix est seulement consigné dans les métadonnées `revoke_sessions` de l'enregistrement d'audit `organization_membership.updated` et aucune session n'est révoquée ; la révocation est prévue (`planned`) dans le service d'authentification. |

## Réponse

`200 OK` avec l'appartenance mise à jour et son `ETag`.

```json
{
  "id": "mem_01j9xn5p9s0t4v6w8x0y2z4a6c",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "user_id": "usr_01j9xh2k6p7q1r3s5t7v9w1x3y",
  "status": "active",
  "source": "admin_api",
  "reason": null,
  "roles": [
    {
      "role_id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
      "source": "admin_api",
      "assigned_at": "2026-10-12T09:31:00.123456Z"
    }
  ],
  "expires_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z",
  "activated_at": "2026-10-12T09:31:00.123456Z",
  "suspended_at": null,
  "removed_at": null,
  "updated_at": "2026-10-12T09:31:00.123456Z",
  "version": 2
}
```

## Erreurs

| HTTP | code | Quand |
|---|---|---|
| 404 | `not_found` | L'appartenance n'existe pas dans cette organisation. |
| 403 | `role_not_assignable` | Un rôle n'est ni un rôle de l'environnement ni un rôle de cette organisation. |
| 409 | `conflict` | `role_version` ne correspond pas à la version actuelle de l'appartenance. |
| 409 | `last_org_admin` | La modification laisserait l'organisation sans administrateur actif. |
| 422 | `validation_failed` | `role_ids` est absent ou invalide, ou `role_version` est inférieur à 1. |
| 401 | `unauthenticated` | L'identifiant d'accès est absent, invalide ou révoqué. |
| 403 | `insufficient_permissions` | L'identifiant d'accès ne dispose pas de l'autorisation requise. L'attribution d'un rôle privilégié (`is_privileged`) exige aussi `roles:write` ; sans elle, rien n'est écrit et `required_permissions` liste les deux autorisations. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; réessayez après la durée indiquée par `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez après la durée indiquée par `Retry-After`. |

## Exemple

```bash
curl -i -X PUT "https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/memberships/mem_01j9xn5p9s0t4v6w8x0y2z4a6c/roles" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_ids":["rol_01j9xr7s1t2w6x8y0z2a4b6c8e","rol_01j9xs8t2v3x7y9z1a3b5c7d9f"],"role_version":1}'
```

## Données personnelles

Cet point de terminaison traite des données personnelles : appartenances aux organisations et invitations. [Données personnelles dans les API KeenAuth](/docs/policies/personal-data) décrit les données stockées, leur durée de conservation et leur suppression. N'envoyez de données personnelles sensibles (santé, données biométriques, convictions religieuses, opinions politiques, orientation sexuelle) dans aucun champ.