Roles

A role is a set of permissions. Five roles are built in; the organization can create others and assign them to a member, to a group (all its members) or to a label (everyone who carries it). A member holds the union of their base role and the roles they receive.

All routes are under https://chat.realmoon.ai/api/v1/orgs/{org_id}. Scopes: roles:read to read, roles:write to write. A write never grants more than the key’s own permissions (403 role_escalation, with permission).

Permissions#Link to the Permissions section

A permission has a reach: org (the whole organization), managed_groups (the groups the person manages) or self (their own data).

A role’s permissions dictionary maps a permission to a reach:

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

Built-in roles#Link to the Built-in roles section

The API returns the names of built-in roles in French; the English app shows the name in parentheses.

The manager role acts on the groups the person manages (see Groups). A custom role has custom:<id> as its role_key.

The role object#Link to the The role object section

{
  "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 is a readable identifier, unique in the organization; assignments use role_key.

List roles#Link to the List roles section

GET /roles · roles:read

Parameters: page, limit (pagination of custom roles, sorted by name). The response also includes builtin (the five built-in roles, with their permissions) and permission_catalog (each permission: key, allowed scopes, owner_only).

Create a role#Link to the Create a role section

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

An organization can have up to 100 custom roles.

Read a role#Link to the Read a role section

GET /roles/{role_id} · roles:read

role_id is the ID of a custom role (id, not custom:<id>) or the key of a built-in role (owner, admin…). A custom role also carries assignment_count, its number of assignments.

Update a role#Link to the Update a role section

PATCH /roles/{role_id} · roles:write

Optional fields name, description (null clears it) and permissions (replaces everything; null removes every permission). key does not change. You must hold both the role’s current permissions and the new ones. Members who have the role get its new permissions right away. A built-in role returns 404.

Delete a role#Link to the Delete a role section

DELETE /roles/{role_id} · roles:write

Deletes the role, its assignments and its rules. Response: {"success": true, "assignments_removed": 3}.

Assignments#Link to the Assignments section

The assignment object#Link to the The assignment object section

{
  "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 is user, group or label; subject_name gives the member’s name, the group’s name or the label’s key = value.

List assignments#Link to the List assignments section

GET /role-assignments · roles:read

Only explicit assignments are listed, not members’ base roles.

Assign a role#Link to the Assign a role section

POST /role-assignments · roles:write

The response is the assignment with created: false if it already existed (the request has no effect and also returns 200).

Remove an assignment#Link to the Remove an assignment section

DELETE /role-assignments · roles:write

Identify the assignment with ?id=<id>, or with a {role_key, subject_type, subject_id} body. Response: {"success": true}. Removing admin is reserved for the owner, and refused if no active admin would be left (409).

See also#Link to the See also section

• Groups
• Labels
• Rules, for rules specific to a role