# Rôles

> Créer des rôles avec leurs permissions et les attribuer à des membres, des groupes ou des étiquettes par l’API d’administration, avec le catalogue des droits.

Un rôle est un ensemble de permissions. Cinq rôles sont fournis ; l’organisation peut en créer d’autres et les attribuer à un membre, à un groupe (tous ses membres) ou à une étiquette (tous ceux qui la portent). Un membre détient l’union de son rôle de base et des rôles reçus.

Toutes les routes sont sous `https://chat.realmoon.ai/api/v1/orgs/{org_id}`. Portées : `roles:read` pour lire, `roles:write` pour écrire. Une écriture ne donne jamais plus que les permissions de la clé (`403 role_escalation`, avec `permission`).

## Permissions

Une permission a une étendue : `org` (toute l’organisation), `managed_groups` (les groupes dont la personne est gestionnaire) ou `self` (ses propres données).

| Permission | Étendues | Permet |
| --- | --- | --- |
| `org.settings` | `org` | Modifier les réglages de l’organisation. |
| `org.delete`, `org.transfer` | `org` | Supprimer, transférer l’organisation. Réservées au propriétaire, jamais dans un rôle créé. |
| `billing.read`, `billing.manage` | `org` | Lire, gérer la facturation. |
| `members.read` | `org`, `managed_groups` | Voir les membres (les adresses e-mail seulement en `org`). |
| `members.invite` | `org`, `managed_groups` | Inviter. |
| `members.import` | `org` | Importer un fichier CSV. |
| `members.suspend`, `members.remove` | `org`, `managed_groups` | Suspendre, retirer. |
| `members.assign_roles` | `org` | Attribuer des rôles. |
| `roles.manage` | `org` | Créer et modifier les rôles. |
| `groups.create`, `groups.delete` | `org` | Créer, supprimer des groupes. |
| `groups.members` | `org`, `managed_groups` | Ajouter et retirer des membres d’un groupe. |
| `groups.rules` | `org` | Changer les règles d’un groupe et la règle d’un groupe dynamique. |
| `groups.instructions` | `org`, `managed_groups` | Écrire les instructions d’un groupe. |
| `labels.manage` | `org` | Créer et modifier les étiquettes. |
| `labels.assign` | `org`, `managed_groups` | Poser des étiquettes sur des membres. |
| `policies.org` | `org` | Changer les règles de l’organisation. |
| `models.manage` | `org` | Gérer les modèles de l’organisation. |
| `connectors.manage` | `org` | Gérer les serveurs MCP. |
| `storage.manage` | `org` | Gérer le stockage. |
| `library.manage` | `org` | Partager les bases de connaissances. |
| `catalog.publish` | `org` | Partager les agents. |
| `usage.read` | `org`, `managed_groups`, `self` | Lire l’utilisation. |
| `usage.export` | `org`, `managed_groups` | Exporter l’utilisation. |
| `security.manage` | `org` | Domaines, connexion unique, SCIM, comptes. |
| `audit.read`, `audit.export` | `org` | Lire, exporter le journal d’audit. |
| `licenses.read`, `licenses.manage` | `org` | Lire, attribuer les licences. |
| `api.manage` | `org` | Gérer les clés d’administration et les webhooks. Jamais par une clé. |

Le dictionnaire `permissions` d’un rôle associe une permission à une étendue :

```json
{ "members.read": "managed_groups", "groups.members": "managed_groups", "usage.read": "self" }
```

## Rôles fournis

| `role_key` | Nom | Permissions | Attribuable |
| --- | --- | --- | --- |
| `owner` | Propriétaire | Toutes | non (rôle de base) |
| `admin` | Administrateur | Toutes sauf `org.delete`, `org.transfer` et `billing.manage` | oui, par le propriétaire seulement |
| `manager` | Selon le type d’organisation : « Gestionnaire », « Enseignant », « Manager », « Chef de service » | `members.read`, `groups.members`, `groups.instructions`, `labels.assign`, `usage.read`, en `managed_groups` | oui |
| `billing` | Facturation | `billing.read`, `licenses.read` | oui |
| `member` | Selon le type : « Membre », « Élève », « Collaborateur », « Agent » | `usage.read` en `self` | non (tout membre) |

Le rôle `manager` agit sur les groupes dont la personne est gestionnaire (voir [Groupes](https://realmoon.ai/documentation/api-organisations/groupes/#ajouter-membres)). Un rôle créé a pour `role_key` `custom:<id>`.

## L’objet rôle

```json
{
  "id": "5c1e2f8a-7d4b-4c9e-9a1f-2b3c4d5e6f70",
  "org_id": "8c1f2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
  "key": "prof_principal",
  "name": "Professeur principal",
  "description": "Gère sa classe et ses étiquettes.",
  "permissions": { "members.read": "managed_groups", "groups.members": "managed_groups", "labels.assign": "managed_groups" },
  "created_by": "1f2e3d4c-5b6a-4987-8a6b-5c4d3e2f1a0b",
  "created_at": 1793836800,
  "updated_at": 1793836800,
  "role_key": "custom:5c1e2f8a-7d4b-4c9e-9a1f-2b3c4d5e6f70",
  "builtin": false,
  "assignable": true
}
```

`key` est un identifiant lisible, unique dans l’organisation ; les attributions utilisent `role_key`.

## Lister les rôles

`GET /roles` · `roles:read`

Paramètres : `page`, `limit` (pagination des rôles créés, triés par nom). La réponse ajoute `builtin` (les cinq rôles fournis, avec leurs permissions) et `permission_catalog` (chaque permission : `key`, `scopes` permis, `owner_only`).

## Créer un rôle

`POST /roles` · `roles:write`

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `key` | chaîne | oui | 2 à 40 caractères : lettres minuscules sans accent, chiffres et `_`. Pas `owner`, `admin`, `manager`, `billing` ni `member`. |
| `name` | chaîne | oui | 1 à 128 caractères. |
| `description` | chaîne | non | 500 caractères au plus. |
| `permissions` | objet | non | [Permissions](https://realmoon.ai/documentation/api-organisations/roles/#permissions) et leur étendue. `{}` par défaut. |

```bash title="cURL"
curl https://chat.realmoon.ai/api/v1/orgs/$ORG_ID/roles \
  -H "Authorization: Bearer $MOONAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "lecture_utilisation",
    "name": "Lecture de l’utilisation",
    "permissions": {"members.read": "org", "usage.read": "org"}
  }'
```

```python title="Python"
import os
import requests

BASE = f"https://chat.realmoon.ai/api/v1/orgs/{os.environ['ORG_ID']}"
HEADERS = {"Authorization": f"Bearer {os.environ['MOONAI_ADMIN_KEY']}"}

role = requests.post(
    f"{BASE}/roles",
    headers=HEADERS,
    json={
        "key": "lecture_utilisation",
        "name": "Lecture de l’utilisation",
        "permissions": {"members.read": "org", "usage.read": "org"},
    },
    timeout=30,
)
role.raise_for_status()
print(role.json()["role_key"])
```

```javascript title="JavaScript"
const BASE = `https://chat.realmoon.ai/api/v1/orgs/${process.env.ORG_ID}`;
const r = await fetch(`${BASE}/roles`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.MOONAI_ADMIN_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: 'lecture_utilisation',
    name: 'Lecture de l’utilisation',
    permissions: { 'members.read': 'org', 'usage.read': 'org' },
  }),
});
if (!r.ok) throw new Error(await r.text());
console.log((await r.json()).role_key);
```

Une organisation a 100 rôles créés au plus.

| Statut | `code` | Cause |
| --- | --- | --- |
| 400 | `invalid_request` | `key` invalide ou réservée, nom vide, permission inconnue ou réservée au propriétaire, étendue non permise, plus de 100 rôles. |
| 403 | `role_escalation` | Le rôle donnerait une permission que la clé n’a pas. |
| 409 | `invalid_request` | « Un rôle avec cet identifiant existe déjà. » |

## Lire un rôle

`GET /roles/{role_id}` · `roles:read`

`role_id` est l’identifiant d’un rôle créé (`id`, pas `custom:<id>`) ou la clé d’un rôle fourni (`owner`, `admin`…). Un rôle créé porte en plus `assignment_count`, son nombre d’attributions.

## Modifier un rôle

`PATCH /roles/{role_id}` · `roles:write`

Champs facultatifs `name`, `description` (`null` l’efface) et `permissions` (remplace tout ; `null` retire toutes les permissions). `key` ne change pas. Il faut détenir les permissions actuelles du rôle et les nouvelles. Les membres qui ont le rôle reçoivent ses nouvelles permissions tout de suite. Un rôle fourni répond `404`.

## Supprimer un rôle

`DELETE /roles/{role_id}` · `roles:write`

Supprime le rôle, ses attributions et ses règles. Réponse : `{"success": true, "assignments_removed": 3}`.

## Attributions

### L’objet attribution

```json
{
  "id": "0d9c8b7a-6f5e-4d3c-8b2a-190817263544",
  "org_id": "8c1f2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
  "role_key": "custom:5c1e2f8a-7d4b-4c9e-9a1f-2b3c4d5e6f70",
  "subject_type": "group",
  "subject_id": "3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b",
  "created_by": "1f2e3d4c-5b6a-4987-8a6b-5c4d3e2f1a0b",
  "created_at": 1793836800,
  "subject_name": "Classe de 3A",
  "role_name": "Professeur principal"
}
```

`subject_type` vaut `user`, `group` ou `label` ; `subject_name` donne le nom du membre, du groupe ou `clé = valeur` de l’étiquette.

### Lister les attributions

`GET /role-assignments` · `roles:read`

| Paramètre | Type | Description |
| --- | --- | --- |
| `role_key` | chaîne | Un rôle (`manager`, `custom:<id>`…). |
| `subject_type` | chaîne | `user`, `group` ou `label`. |
| `subject_id` | chaîne | Un membre, un groupe ou une étiquette. |
| `page`, `limit` | entier | Pagination. |

Seules les attributions explicites sont listées, pas le rôle de base des membres.

### Attribuer un rôle

`POST /role-assignments` · `roles:write`

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `role_key` | chaîne | oui | `admin`, `manager`, `billing` ou `custom:<id>`. |
| `subject_type` | chaîne | oui | `user`, `group` ou `label`. |
| `subject_id` | chaîne | oui | L’identifiant du membre (actif ou suspendu), du groupe ou de l’étiquette. |

La réponse est l’attribution avec `created` : `false` si elle existait déjà (la requête est sans effet et répond aussi `200`).

| Statut | `code` | Cause |
| --- | --- | --- |
| 400 | `invalid_request` | `owner` ou `member` (ils viennent du rôle de base) ; rôle inconnu. |
| 400 | `scim_group_role` | Un groupe venu de l’annuaire SCIM ne donne pas de rôle. |
| 403 | `forbidden` | Nommer un administrateur (propriétaire seulement, donc jamais par une clé) ; s’attribuer un rôle ; viser le propriétaire. |
| 403 | `license_change_forbidden` | Le changement ferait changer de lot de licences des membres ; il faut la permission de gérer les licences (portée `licenses:write`). Porte `user_ids` et `count`. |
| 404 | `not_found` | Membre, groupe ou étiquette introuvable. |
| 409 | `directory_group_admin` | Le rôle `admin` sur un groupe rempli par l’annuaire ou la connexion unique. |

### Retirer une attribution

`DELETE /role-assignments` · `roles:write`

Désignez l’attribution par `?id=<id>`, ou par un corps `{role_key, subject_type, subject_id}`. Réponse : `{"success": true}`. Retirer `admin` est réservé au propriétaire, et refusé s’il ne resterait aucun administrateur actif (`409`).

## Voir aussi

- [Groupes](https://realmoon.ai/documentation/api-organisations/groupes/)
- [Étiquettes](https://realmoon.ai/documentation/api-organisations/etiquettes/)
- [Règles](https://realmoon.ai/documentation/api-organisations/regles/), pour les règles propres à un rôle

---

Documentation Moon AI › API des organisations › Rôles. Page : https://realmoon.ai/documentation/api-organisations/roles/. Modifiée le 5 novembre 2026.

© 2026 Stellarr Studio SAS. Tous droits réservés. Moon AI, Moon Blur et Stellarr Studio sont des marques déposées à l’INPI.