Rôles

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#Lien vers la section 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).

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

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

Rôles fournis#Lien vers la section Rôles fournis

Le rôle manager agit sur les groupes dont la personne est gestionnaire (voir Groupes). Un rôle créé a pour role_key custom:<id>.

L’objet rôle#Lien vers la section L’objet rôle

{
  "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#Lien vers la section 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#Lien vers la section Créer un rôle

POST /roles · roles:write

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

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"])

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.

Lire un rôle#Lien vers la section 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#Lien vers la section 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#Lien vers la section 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#Lien vers la section Attributions

L’objet attribution#Lien vers la section L’objet attribution

{
  "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#Lien vers la section Lister les attributions

GET /role-assignments · roles:read

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

Attribuer un rôle#Lien vers la section Attribuer un rôle

POST /role-assignments · roles:write

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).

Retirer une attribution#Lien vers la section 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#Lien vers la section Voir aussi

• Groupes
• Étiquettes
• Règles, pour les règles propres à un rôle