Créer un rôle d'environnement

POST /v1/roles · autorisation roles:write

Crée un rôle dans le catalogue de rôles de l'environnement. La réponse contient un ETag ; l'écriture est auditée sous role.created. Idempotency-Key est facultatif.

Requête

Champ Type Obligatoire Description
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é : en libre-service, seul un membre détenant le rôle d'administrateur de l'organisation (org_admin_role_id) peut l'attribuer, et associer un groupe externe à ce rôle exige roles:write et une approbation.
assignable_in_self_service boolean non Vaut true par défaut, y compris pour un rôle privilégié.

Réponse

201 Created avec le rôle.

{
  "id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
  "organization_id": null,
  "key": "support",
  "name": "Support",
  "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
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.
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/roles" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"support","name":"Support"}'