Référence API

Automatisez EduShell depuis vos propres outils. L'API est une interface REST sur HTTPS, authentifiée par des clés API d'organisation.

URL de base

Toutes les requêtes API vont vers l'URL de base versionnée, en HTTPS :

bash

https://edushell.app/api/v1

Les requêtes et les réponses sont en JSON. Envoyez sur les requêtes qui portent un corps.

Authentification

Authentifiez-vous avec une clé API. Créez-en une dans Administration > Clés API ; la clé complète est affichée une seule fois, à la création, et ressemble à . Conservez-la comme un secret. Une clé porte un rôle ( ou ) et agit au sein de l'organisation qui l'a émise.

Envoyez-la en jeton Bearer sur chaque requête :

bash

curl https://edushell.app/api/v1/me \
  -H "Authorization: Bearer esk_votre_cle_ici"

Une clé absente, malformée ou révoquée renvoie . Révoquez une clé à tout moment depuis le même écran ; elle cesse de fonctionner immédiatement.

Traitez une clé API comme un mot de passe : elle agit avec le rôle que vous lui avez donné, sur toute votre organisation. Ne la mettez jamais dans du code côté client, un dépôt public ou une URL. Si l'une fuite, révoquez-la et émettez-en une nouvelle.

Conventions

HTTPS uniquement. Le HTTP en clair n'est pas servi.
JSON partout. Les corps sont en JSON ; les horodatages sont en ISO 8601 UTC (par exemple ) ; les identifiants sont des UUID.
Méthodes. lit, crée, met à jour, supprime.
Portée. Une clé est liée à son organisation ; vous ne passez jamais d'identifiants pour une autre org, et ne pouvez pas lire d'une org à l'autre.

Erreurs

Les erreurs utilisent les codes de statut HTTP standards et une enveloppe JSON cohérente :

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

Statut	Signification
400	La requête était malformée
401	Clé absente, invalide ou révoquée
403	Le rôle de la clé ne permet pas cette action
404	Aucune ressource de ce type dans votre org
409	Conflit, par exemple un nom déjà pris
429	Débit limité, ralentissez

Limites de débit

Les requêtes sont limitées en débit par appelant. Quand vous dépassez le budget, l'API renvoie avec l'enveloppe d'erreur standard ; temporisez et réessayez. Les budgets sont généreux pour une automatisation normale ; si vous importez en lot, ajoutez une courte pause entre les appels plutôt que de réessayer un 429 immédiatement.

Points d'accès

L'API reflète ce que fait la console. Les points d'accès les plus utiles :

Méthode et chemin	Rôle
	Le principal authentifié et son org
	Lister les membres
	Changer le rôle d'un membre
	Retirer un membre
	Le journal d'activité de l'organisation
et	Lister ou créer des sessions
et	Lire ou supprimer une session
	Régénérer le code de session
et	Lister ou créer des labs
	Lister les versions d'un lab
	Gérer les clés API
	Gérer les points de webhook

Chaque chemin est relatif à l'URL de base. Les identifiants sont des UUID renvoyés par les points de liste.

Vous voulez réagir aux changements plutôt que d'interroger en boucle ? Abonnez-vous aux webhooks et EduShell enverra des événements signés en POST vers votre point d'accès.