Premiers pas avec l’API

L’API publique de Maketools permet à vos outils (tableau de bord BI, LMS, entrepôt de données) de lire les rapports de vos jeux forkés sans que personne ne se connecte. Elle est en lecture seule et versionnée sous /api/v1/. Elle est incluse dans les offres Pro et Enterprise.

1. Créer une clé d’API

Les propriétaires et les admins (avec la vérification en deux étapes) créent les clés dans Organisation → Clés d’API :

1. Choisissez un nom qui dit où la clé servira (par exemple Power BI).
2. Choisissez ses scopes, et rien de plus que ce dont l’outil a besoin :
   • forks:read : lister les forks de l’organisation et lire leur statut ;
   • reports:read : lire les statistiques d’un fork et exporter ses parties en CSV.
3. Fixez si possible une date d’expiration. Préférez des clés qui expirent, et renouvelez-les.

La clé a la forme dg_live_<id>_<secret>. Elle ne s’affiche qu’une seule fois : copiez-la tout de suite dans le coffre de secrets de votre outil. Maketools ne garde qu’une empreinte du secret et ne peut pas le réafficher. Une clé perdue se révoque et se remplace.

2. Appeler l’API

Envoyez la clé dans l’en-tête Authorization de chaque requête :

curl -H "Authorization: Bearer $MAKETOOLS_API_KEY" \
  "https://<votre-site-maketools>/api/v1/forks"

Puis lisez les statistiques d’un fork sur une période (jours ISO inclus, 366 jours au plus) :

curl -H "Authorization: Bearer $MAKETOOLS_API_KEY" \
  "https://<votre-site-maketools>/api/v1/forks/<forkId>/stats?from=2026-09-01&to=2026-09-30"

Ou exportez ses parties en CSV :

curl -H "Authorization: Bearer $MAKETOOLS_API_KEY" -o parties.csv \
  "https://<votre-site-maketools>/api/v1/forks/<forkId>/exports/csv?from=2026-09-01&to=2026-09-30"

Tous les endpoints, leurs paramètres et leurs réponses sont décrits dans la référence de l’API, générée depuis le code. La spécification OpenAPI est servie en /openapi/v1.json pour générer un client.

Ce qu’une clé peut faire

• Une clé ne fonctionne que sur /api/v1/*. Tout autre endpoint la refuse (403).
• Une clé ne voit que son organisation. Demander un fork d’une autre organisation est refusé (403), et la tentative est inscrite dans votre journal d’audit.
• Une clé n’écrit jamais rien, ne joue jamais et ne voit jamais la configuration d’un fork.
• Les rapports suivent les règles du tableau de bord : les joueurs sont pseudonymes sauf si votre organisation a choisi le mode nominatif, et un groupe de moins de 5 joueurs n’est jamais détaillé.
• Chaque clé peut envoyer 120 requêtes par minute ; au-delà, l’API répond 429 (ERR_RATE_LIMITED).

Sécurité et audit

• La création et la révocation d’une clé, et chaque usage refusé (mauvais secret, clé révoquée ou expirée, scope insuffisant, autre organisation, endpoint hors de /api/v1/*), sont inscrits dans le journal d’audit de l’organisation.
• Révoquez une clé dès qu’elle ne sert plus ou qu’elle a pu fuiter : elle cesse aussitôt de fonctionner. La liste indique la dernière utilisation de chaque clé.
• Si votre organisation passe sous l’offre Pro, ses clés cessent de fonctionner ; elles restent visibles et révocables.