# Créer un rôle d'organisation

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

Crée un rôle dans l'organisation, sans autorisations ; ajoutez-les avec [Définir les autorisations d'un rôle](./set-permissions). Une organisation compte au maximum 50 rôles. 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 API front (`Authorization: DPoP <token>` avec une preuve DPoP ; voir [Jeton d'accès API front](/docs/api/fapi/front-api-token)). L'utilisateur doit être un 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 forfait.

## Requête

En-têtes :

| En-tête | Requis | Description |
| --- | --- | --- |
| `Idp-Client` | oui | Identifiant du SDK. |
| `Origin` | oui | Doit être exactement `https://<sign-in host>`. |
| `Content-Type` | oui | `application/json`. |

`org_id` : l'identifiant de l'organisation (`org_…`).

Corps :

| Champ | Requis | Description |
| --- | --- | --- |
| `key` | oui | Clé du rôle ; unique dans l'organisation et parmi les rôles de l'environnement ; ne peut plus être modifiée ensuite. |
| `name` | oui | Nom d'affichage. |
| `description` | non | Description. |

## Réponse

`201 Created` avec les en-têtes `Location` et `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` | Le forfait 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. |
| 404 | `not_found` | Aucune organisation ou aucun rôle de ce type pour cet utilisateur (un identifiant inconnu, mal formé ou étranger reçoit la même réponse). |
| 409 | `role_key_conflict` | La clé est déjà utilisée dans l'organisation ou par un rôle de l'environnement. |
| 409 | `role_limit_reached` | L'organisation compte déjà 50 rôles. |
| 409 | `organization_pending_deletion` | L'organisation est programmée pour suppression. |
| 422 | `validation_failed` | Un champ est absent ou invalide ; `errors[]` le désigne. |
| 503 | `service_unavailable` | Service temporairement indisponible ; réessayez après `Retry-After`. |

## Exemple

```bash
curl -X POST https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"key":"auditor","name":"Auditor"}'
```