API d’administration

L’API d’administration fait par programme ce que fait l’administration d’une organisation : votre annuaire, votre logiciel RH ou un script invite des membres, tient les groupes à jour, attribue des licences ou lit l’utilisation. Elle est ouverte à tout workspace d’équipe ; les groupes, les rôles, les règles et la sécurité ne servent que dans une organisation gérée.

https://chat.realmoon.ai/api/v1/orgs/{org_id}

L’identifiant de l’organisation (org_id) figure dans l’administration › « API et clés », carte « Démarrage », dans l’exemple « Premier appel ».

Créer une clé d’administration#Lien vers la section Créer une clé d’administration

1. Ouvrez l’administration › « API et clés », carte « Clés d’administration », puis cliquez sur « Nouvelle clé ».
2. Saisissez un « Nom » qui dit qui l’utilise, par exemple « Logiciel RH » (80 caractères au plus).
3. Dans « Droits », choisissez pour chaque domaine « Aucun accès », « Lecture » ou « Lecture et écriture ». Choisissez au moins un droit.
4. Choisissez l’« Expiration » : « Jamais » ou « Dans … jours » (730 jours au plus).
5. Facultatif : dans « Adresses autorisées », une adresse IP ou une plage par ligne, par exemple 203.0.113.0/24 (50 au plus). Laissez vide pour accepter toutes les adresses.
6. Cliquez sur « Créer la clé », copiez-la, puis cliquez sur « Je l’ai copié ». Elle commence par moai_adm_ et ne sera plus affichée.

La page est visible du propriétaire, des administrateurs et des rôles qui ont la permission de gérer l’API. Une organisation a 25 clés actives au plus. La liste affiche le début de chaque clé (moai_adm_ et six caractères), son créateur, sa date d’expiration et sa dernière utilisation.

Les droits d’une clé ne changent plus après sa création : « Modifier » ne change que son nom et ses adresses autorisées. Pour d’autres droits, créez une nouvelle clé. « Révoquer » arrête une clé tout de suite et définitivement.

Authentifier les requêtes#Lien vers la section Authentifier les requêtes

Envoyez la clé dans l’en-tête Authorization, après Bearer. Toutes les requêtes passent en HTTPS.

Authorization: Bearer moai_adm_…

• Une clé ne fonctionne que pour les routes /api/v1/orgs/{org_id}/… de son organisation. Avec l’identifiant d’une autre organisation, la réponse est 404 not_found, comme pour une organisation qui n’existe pas.
• Hors de ces routes (chat, autres API), la clé est refusée : 403 admin_key_scope_forbidden.
• Une clé personnelle sk-… est refusée sur ces routes : 403 personal_api_key_forbidden.
• Avec des adresses autorisées, une requête venue d’une autre adresse reçoit 403 admin_key_ip_forbidden.

Lire l’accès de la clé#Lien vers la section Lire l’accès de la clé

GET /me · aucune portée requise

Le premier appel conseillé : il confirme que la clé fonctionne et donne ses permissions effectives.

curl https://chat.realmoon.ai/api/v1/orgs/$ORG_ID/me \
  -H "Authorization: Bearer $MOONAI_ADMIN_KEY"

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

r = requests.get(f"{BASE}/me", headers=HEADERS, timeout=30)
r.raise_for_status()
me = r.json()
print(me["org"]["name"], sorted(me["permissions"]))

const BASE = `https://chat.realmoon.ai/api/v1/orgs/${process.env.ORG_ID}`;
const HEADERS = { Authorization: `Bearer ${process.env.MOONAI_ADMIN_KEY}` };

const r = await fetch(`${BASE}/me`, { headers: HEADERS });
if (!r.ok) throw new Error(await r.text());
const me = await r.json();
console.log(me.org.name, Object.keys(me.permissions));

{
  "org": {
    "id": "8c1f2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
    "name": "Lycée Jean Moulin",
    "slug": "lycee-jean-moulin",
    "is_personal": false,
    "org_kind": "education",
    "managed": true,
    "policy_version": 14
  },
  "my_role": "api_key",
  "roles": [],
  "permissions": {
    "members.read": "org",
    "members.invite": "org",
    "members.suspend": "org",
    "members.remove": "org",
    "usage.read": "self"
  },
  "managed_group_ids": [],
  "group_ids": [],
  "kind": "education",
  "managed": true,
  "platform_override": false,
  "labels_display": { "manager": "Enseignant", "member": "Élève" },
  "labels_display_en": { "manager": "Teacher", "member": "Student" },
  "my_groups": [],
  "role_names": {},
  "can_leave": false
}

Les autres champs décrivent la personne qui a créé la clé (joined_at, license, can_leave) ou restent vides pour une clé.

Portées#Lien vers la section Portées

Chaque domaine de l’écran « Droits » correspond à deux portées. Une portée …:read n’ouvre que les lectures (GET) ; une portée …:write ouvre aussi les lectures de son domaine.

Quelques routes demandent une portée différente de celle de leur domaine :

Une route sans la portée voulue répond 403 admin_key_scope_missing, avec la liste required_scopes des portées qui conviennent.

Les droits du créateur#Lien vers la section Les droits du créateur

La portée ouvre une route ; la permission décide de l’action. À chaque requête, la clé reçoit les permissions de la personne qui l’a créée, limitées à celles de ses portées. Une clé n’a donc jamais plus de droits que son créateur :

• si son créateur ne lit que les membres des groupes qu’il gère, la clé ne lit qu’eux aussi, sans leur adresse e-mail ;
• vous ne pouvez donner à une clé que des domaines où vous avez au moins une permission (sinon 403 role_escalation à la création) ;
• une action qui donnerait plus que les permissions de la clé est refusée : 403 role_escalation, avec la permission en cause.

La clé est révoquée définitivement quand son créateur quitte l’organisation ou perd la permission de gérer l’API. Elle est refusée tant que son compte ou son adhésion est suspendu (403 admin_key_creator_inactive).

Ce qu’une clé ne fait jamais#Lien vers la section Ce qu’une clé ne fait jamais

• Supprimer l’organisation ou en transférer la propriété.
• Payer ou changer la facturation.
• Créer, modifier ou révoquer des clés d’administration.
• Configurer la connexion unique ou le jeton de l’annuaire SCIM (403 owner_only) ; elle peut seulement les lire.
• Nommer un administrateur, ou agir sur le propriétaire, un administrateur ou son propre créateur.
• Utiliser le chat ou toute autre API de Moon AI.

Pagination#Lien vers la section Pagination

Les listes acceptent deux paramètres de requête :

Une valeur illisible est remplacée par la valeur par défaut, une valeur hors bornes par la borne la plus proche. Chaque liste répond :

{ "items": [], "total": 0, "page": 1, "limit": 50 }

total compte tous les éléments qui répondent aux filtres. Une liste peut ajouter des champs à côté de items, décrits sur sa page.

Formats#Lien vers la section Formats

• Les corps de requête sont en JSON (Content-Type: application/json), 512 Ko au plus (sinon 413). Seul l’import de membres reçoit un fichier CSV.
• Un champ inconnu dans un corps est refusé : 400 invalid_request, avec fields qui nomme le champ (« Champ inconnu. »).
• Les dates sont des entiers en secondes Unix (UTC).
• Les identifiants (organisation, membre, groupe, rôle créé, étiquette…) sont des chaînes opaques ; ne les construisez pas vous-même.
• Les messages d’erreur sont en français ; fiez-vous au champ code, qui ne change pas.

Erreurs#Lien vers la section Erreurs

Toutes les erreurs ont la même forme :

{
  "detail": {
    "code": "admin_key_scope_missing",
    "message": "Cette clé n’a pas la portée nécessaire pour cette route.",
    "required_scopes": ["members:write"]
  }
}

Les codes propres à une route sont listés sur sa page.

Limites de débit#Lien vers la section Limites de débit

Une clé a 600 requêtes par minute, dont 120 écritures (tout ce qui n’est pas GET). Chaque réponse porte trois en-têtes :

Au-delà, la réponse est 429 rate_limited avec Retry-After. Au-delà de 30 tentatives avec une clé fausse en 10 minutes depuis la même adresse IP, cette adresse reçoit 429 jusqu’à la fin de la fenêtre.

Les tests qui font contacter une adresse extérieure (webhook, serveur MCP, stockage) ont leur propre limite : 20 tests en 10 minutes par personne (pour une clé, son créateur), puis 429 rate_limited.

Requêtes rejouables#Lien vers la section Requêtes rejouables

Un POST accepte l’en-tête Idempotency-Key (1 à 255 caractères visibles, par exemple un UUID). Renvoyez la même requête avec la même clé après une coupure réseau : l’action n’est faite qu’une fois.

• La première réponse est gardée 24 heures et rendue à l’identique, avec l’en-tête Idempotent-Replayed: true.
• La même clé avec un autre corps répond 422 idempotency_key_reused.
• Tant que la première requête tourne, la même clé répond 409 idempotency_in_progress avec Retry-After: 1.
• Les réponses 401, 403, 429, 5xx et celles de plus de 2 Mo ne sont pas gardées : un nouvel essai refait la requête.

La clé d’idempotence vaut pour une clé d’administration : deux clés différentes peuvent utiliser la même valeur sans se gêner.

Description OpenAPI#Lien vers la section Description OpenAPI

La description complète des routes est publique, sans authentification :

https://chat.realmoon.ai/api/v1/orgs/openapi.json

Elle suit OpenAPI 3.1 et porte la version 2026-10-30. Chaque opération indique ses portées dans x-moon-scopes (null quand elle n’est pas ouverte aux clés), son groupe (tags) et, pour les routes qui lisent un corps, le schéma de ce corps. Le schéma Error décrit la forme des erreurs et WebhookEvent celle des événements. Le fichier peut être gardé en cache 5 minutes.

Journal d’audit#Lien vers la section Journal d’audit

Chaque écriture faite avec une clé est inscrite au journal d’audit de l’organisation au nom de la clé : l’acteur vaut api_key:<id de la clé> et son libellé « Clé d’API « nom » ». Lisez-le avec GET /audit.

Routes de l’administration seulement#Lien vers la section Routes de l’administration seulement

Ces routes existent sous /api/v1/orgs/{org_id}/ mais ne répondent qu’à une session ouverte dans l’administration, jamais à une clé (403 admin_key_scope_missing, required_scopes vide) : admin-keys (gestion des clés), api-settings, setup (carte « Mise en route »), transfer et delete.

Référence par domaine#Lien vers la section Référence par domaine

Voir aussi#Lien vers la section Voir aussi

• Organisations gérées
• Webhooks
• API développeur, pour appeler les modèles depuis vos programmes