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. 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). 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).
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
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"}'