Authentification de l'API publique : clés, portées et sécurité

L'API publique de Studeia expose les routes /api/institution/* pour les intégrations. Chaque requête est authentifiée par session (dans l'application) ou par clé API (Bearer). Ce guide couvre les clés, les portées et les bonnes pratiques.

Réponse rapide

Authentifiez-vous avec un Bearer token (clé avec le préfixe mia_)
Les clés sont créées dans Paramètres → API Keys
Les portées selon le modèle ressource:action limitent chaque clé
La clé complète n'apparaît qu'une seule fois (le serveur ne conserve que le hash)
Les opérations sensibles n'acceptent que la session, jamais de clé API

Comment s'authentifier

Envoyez la clé dans le header Authorization :

GET /api/institution/courses
Authorization: Bearer mia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La double authentification (resolveAuth) accepte la session (dans l'application) ou la clé API (intégrations). Pour les clés, la réponse inclut des headers de rate limit.

Portées (principe du moindre privilège)

Les portées suivent le modèle ressource:action. Exemples :

Ressource	Lecture	Écriture
Cours	`courses:read`	`courses:write`
Utilisateurs	`users:read`	`users:write`
Inscriptions	`enrollments:read`	`enrollments:write`
Classes	`classes:read`	`classes:write`
Rapports	`reports:read`	—

Créez des clés avec le minimum de portées nécessaires. Une clé utilisée uniquement pour la lecture de rapports n'a pas besoin de portées d'écriture.

Sécurité de la clé

La clé complète est affichée une seule fois à la création.
Le serveur ne stocke que le hash SHA-256 — la clé ne peut pas être récupérée.
Révoquer/modifier une clé invalide l'accès immédiatement.
En cas de fuite, révoquez-la et générez-en une nouvelle.

Routes qui N'acceptent PAS de clé API

Par mesure de sécurité, les opérations critiques exigent une authentification par session (sessionOnly) et n'acceptent jamais de clé API :

Gestion des clés API.
Billing / checkout (évite l'automatisation des achats).
Modération du superviseur IA.

Bonnes pratiques

Utilisez le moindre privilège pour les portées.
Faites tourner les clés périodiquement.
N'exposez jamais la clé dans le frontend ou dans des dépôts.
Surveillez l'utilisation (chaque requête est enregistrée).
Gérez les rate limits (consultez la page dédiée).

Questions fréquentes

Comment s'authentifier ? Bearer token avec la clé mia_ dans le header Authorization.

Que sont les portées ? Les limites ressource:action de ce que la clé peut faire.

La clé est-elle visible ensuite ? Non — uniquement à la création ; le serveur ne conserve que le hash.

Fonctionne pour toutes les routes ? Pour la plupart ; billing, clés et modération sont réservés à la session.

Consultez la vue d'ensemble de l'API et webhooks et rate limits.

FAQ

Comment authentifier une requête sur l'API de Studeia ?

Envoyez la clé API dans le header Authorization en tant que Bearer token. Les clés ont le préfixe mia_ et sont générées dans Paramètres → API Keys de l'institution. Chaque requête est également soumise au rate limiting, et l'utilisation est enregistrée à des fins d'audit.

Que sont les portées (scopes) et pourquoi sont-elles importantes ?

Les portées limitent ce que chaque clé peut faire, selon le modèle ressource:action (ex. : courses:read, users:write). Une clé ne peut exécuter que les opérations couvertes par ses portées. Créez des clés avec le minimum de portées nécessaires (principe du moindre privilège) — une clé de lecture ne doit pas avoir de portées d'écriture.

La clé API complète est-elle visible après sa création ?

Non. La clé complète n'est affichée qu'une seule fois, au moment de la création. Le serveur stocke uniquement un hash (SHA-256), de sorte que la clé ne peut pas être récupérée ensuite. Conservez-la en lieu sûr ; en cas de perte, révoquez-la et générez-en une nouvelle.

Puis-je utiliser la clé API pour n'importe quelle route institutionnelle ?

Pour la plupart des routes /api/institution/*, oui — avec la portée correcte. Exceptions : les opérations sensibles (gestion des clés API, billing/checkout, modération du superviseur IA) n'acceptent que l'authentification par session (sessionOnly), jamais de clé API, afin d'éviter l'automatisation d'actions critiques.