Créer un rôle d'organisation

POST /v1/organizations/{org_id}/roles · autorisation roles:write

Crée un rôle personnalisé qui n'existe que dans cette organisation. Les rôles d'organisation exigent la fonctionnalité de forfait org_custom_roles, ne peuvent pas être privilégiés, et ne peuvent pas être créés tant que la liste des autorisations permises pour les rôles d'organisation de l'environnement est vide. La réponse contient un ETag ; l'écriture est auditée sous role.created. Idempotency-Key est facultatif.

Requête

Champ Type Obligatoire Description
org_id path oui Identifiant de l'organisation (org_…).
key string oui Lettres minuscules, chiffres, _ et - ; 1 à 64 caractères ; unique dans son périmètre et immuable.
name string oui Nom d'affichage, jusqu'à 128 caractères.
description string non Jusqu'à 1024 caractères.
is_privileged boolean non Marque un rôle privilégié (non autorisé pour les rôles d'organisation).
assignable_in_self_service boolean non Vaut true par défaut.

Réponse

201 Created avec le rôle.

{
  "id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "key": "billing-admin",
  "name": "Billing admin",
  "description": "",
  "is_privileged": false,
  "assignable_in_self_service": true,
  "permission_ids": [],
  "created_at": "2026-10-12T09:31:00.123456Z",
  "updated_at": "2026-10-12T09:31:00.123456Z",
  "version": 1
}

Erreurs

HTTP code Quand
404 not_found L'organisation n'existe pas dans cet environnement.
403 org_custom_roles_disabled Les rôles d'organisation sont désactivés dans cet environnement.
403 plan_feature_unavailable Le forfait n'inclut pas les rôles d'organisation (Business et supérieurs).
409 role_key_conflict Un rôle avec cette key existe déjà dans le périmètre.
409 role_limit_reached La limite de 1 000 rôles d'environnement ou de 50 rôles par organisation est atteinte.
422 validation_failed Un champ est absent ou invalide, ou is_privileged vaut true.
401 unauthenticated Le justificatif est absent, invalide ou révoqué.
403 insufficient_permissions Le justificatif ne dispose pas de l'autorisation requise.
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

curl -i -X POST "https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/roles" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"billing-admin","name":"Billing admin"}'