Intégration · Référence
Accès API
Authentifiez-vous avec des clés API limitées et utilisez les endpoints en toute sécurité.
L'API HTTP de Kokobi permet à vos systèmes de gérer les ressources pédagogiques et de lire la progression sans reproduire les actions d'un administrateur dans le navigateur. La référence OpenAPI interactive se trouve à /api/docs.
Créer une clé API
Les propriétaires et administrateurs peuvent gérer les clés API de l'organisation depuis le sélecteur d'organisation dans la barre latérale d'administration :
- Ouvrez Administration, puis le sélecteur d'organisation.
- Choisissez Clés API.
- Saisissez un nom descriptif pour l'intégration.
- Créez la clé.
- Copiez immédiatement le secret et conservez-le dans un gestionnaire de secrets.
La clé complète n'est affichée qu'au moment de sa création. Utilisez une clé différente pour chaque application afin de pouvoir révoquer une intégration sans interrompre les autres.
Les clés API sont limitées à une organisation et soumises aux mêmes limites de débit que le compte associé. L'organisation de la clé devient l'organisation active pour les opérations API authentifiées.
Authentifier les requêtes
Envoyez la clé dans l'en-tête x-api-key :
curl "https://votre-hote-kokobi.example/api/courses" \
--header "x-api-key: $KOKOBI_API_KEY" \
--header "accept: application/json"Ne placez jamais une clé API dans une URL, du code exécuté dans le navigateur, des journaux, des propriétés d'analyse ou un fichier de configuration versionné.
Trouver un endpoint
Ouvrez /api/docs pour consulter le catalogue actuel des endpoints, les schémas de requête et de réponse ainsi que les erreurs possibles. Les principaux groupes couvrent :
- Les cours, modules, apprenants, partages et statistiques.
- Les collections, l'ordre des cours et les apprenants des collections.
- Les cours, tentatives et collections côté apprenant.
- Les organisations, domaines et apprenants de l'organisation.
- La configuration des webhooks et l'historique des livraisons.
- La lecture publique des cours, collections et organisations.
Utilisez l'opération et le schéma présentés dans la référence interactive comme source de vérité. L'API est servie sous /api sur l'hôte Kokobi principal et sur le domaine personnalisé actif d'une organisation.
Localisation
Les endpoints localisés choisissent l'anglais ou le français à partir de la première valeur disponible :
- Un paramètre de requête
locale. - Un en-tête de requête
locale. - Le témoin de langue.
- L'en-tête
Accept-Language. - L'anglais par défaut.
Certains endpoints de ressources proposent aussi une langue de repli. Consultez le schéma dans /api/docs avant de désactiver ce repli.
Exemple :
curl "https://votre-hote-kokobi.example/api/courses?locale=fr" \
--header "x-api-key: $KOKOBI_API_KEY" \
--header "accept: application/json"Erreurs
Traitez explicitement les codes d'état. Les réponses varient selon l'opération; utilisez les schémas d'erreur de la référence interactive comme source de vérité.
| Statut | Signification courante |
|---|---|
400 | La requête ne respecte pas le schéma de l'endpoint. |
401 | La clé API est absente, invalide, désactivée ou expirée. |
403 | La clé est valide, mais n'a pas accès à l'opération ou à la ressource. |
404 | La ressource n'existe pas dans le périmètre de l'organisation de la clé. |
409 | La requête entre en conflit avec l'état existant. |
500 | Kokobi n'a pas pu terminer l'opération. |
Validez les données envoyées, n'effectuez des nouvelles tentatives limitées que pour les erreurs transitoires et ne répétez jamais une erreur de validation ou de permission sans modifier la requête.
Bonnes pratiques de sécurité
- Conservez la clé dans un gestionnaire de secrets côté serveur.
- Accordez et utilisez uniquement les accès nécessaires à l'intégration.
- Renouvelez les clés régulièrement et immédiatement après une exposition possible.
- Supprimez les clés qui ne sont plus utilisées.
- Séparez les clés de développement et de production.
- N'exposez pas les données des apprenants à des systèmes qui n'en ont pas besoin.
- Journalisez les identifiants de requête et les codes d'état plutôt que les secrets ou les données personnelles complètes.
Pour les intégrations événementielles, préférez les webhooks à l'interrogation répétée de l'API.