# Mettre à jour un rôle d'organisation

`PATCH /fapi/v1/organizations/{org_id}/roles/{role_id}` · appelé depuis l'hôte de connexion de l'environnement

Modifie le nom ou la description d'un rôle d'organisation (JSON merge patch, RFC 7396). Les rôles d'environnement ne peuvent pas être modifiés ici. Nécessite le cookie `__Host-idp_session` de l'utilisateur authentifié ; si le cookie est absent, expiré ou révoqué, renvoie `401 unauthenticated`. Une application de première partie sur une autre origine peut à la place envoyer son jeton d'accès Front API (`Authorization: DPoP <token>` avec une preuve DPoP ; voir [Jeton d'accès Front API](/docs/api/fapi/front-api-token)). L'utilisateur doit être membre actif de l'organisation disposant de l'autorisation `idp_roles:manage`. Un utilisateur qui n'est pas membre reçoit `404 not_found`, afin que l'existence de l'organisation ne soit pas révélée ; un membre sans cette autorisation reçoit `403 insufficient_permissions`. Les rôles d'organisation doivent être activés pour l'environnement et inclus dans son offre.

## Requête

En-têtes :

| En-tête | Obligatoire | Description |
| --- | --- | --- |
| `Idp-Client` | oui | Identifiant du SDK. |
| `Origin` | oui | Doit être exactement `https://<hôte de connexion>`. |
| `Content-Type` | avec un corps | `application/json` ou `application/merge-patch+json`. |
| `If-Match` | non | `"<version>"` du rôle tel que lu en dernier ; si le rôle a changé depuis, renvoie `412 precondition_failed` et rien ne change. |

`org_id` : l'identifiant de l'organisation (`org_…`). `role_id` : l'identifiant du rôle (`rol_…`).

Corps (au moins un champ) :

| Champ | Obligatoire | Description |
| --- | --- | --- |
| `name` | non | Nouveau nom d'affichage. |
| `description` | non | Nouvelle description. |

## Réponse

`200 OK` avec un nouvel `ETag` ; le corps est le rôle (voir [Obtenir un rôle d'organisation](./get)).

## Erreurs

| Statut | Code | Quand |
| --- | --- | --- |
| 401 | `unauthenticated` | Aucun cookie de session valide. |
| 403 | `origin_not_allowed` | `Origin` est absent ou incorrect. |
| 403 | `insufficient_permissions` | L'utilisateur ne dispose pas de `idp_roles:manage` dans l'organisation. |
| 403 | `plan_feature_unavailable` | L'offre de l'environnement n'inclut pas les rôles d'organisation (`feature`, `required_plan`). |
| 403 | `org_custom_roles_disabled` | Les rôles d'organisation sont désactivés pour l'environnement. |
| 403 | `role_not_assignable` | Le rôle accorde une autorisation que l'utilisateur ne possède pas, ou l'adhésion propre de l'utilisateur la comporte. |
| 404 | `not_found` | Aucune organisation ou aucun rôle d'organisation de ce type pour cet utilisateur ; un rôle d'environnement, ou un identifiant inconnu, mal formé ou étranger, reçoit la même réponse. |
| 409 | `organization_pending_deletion` | L'organisation est programmée pour suppression. |
| 412 | `precondition_failed` | `If-Match` ne correspond pas à la version actuelle, ou le rôle a changé pendant le traitement de la requête. |
| 422 | `validation_failed` | Un champ est invalide, ou le patch est vide (`empty_patch`). |
| 503 | `service_unavailable` | Service temporairement indisponible ; réessayez après `Retry-After`. |

## Exemple

```bash
curl -X PATCH https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -b cookies.txt \
  -d '{"name":"Auditors"}'
```