17. API d’intégration et clés API

L’API d’intégration permet à votre propre programme, tableur ou script de lire automatiquement les données de vos projets : la liste des projets, la liste des câbles et du matériel, le tableau des circuits et la liste des bornes des tableaux de distribution, le métré et la composition du dossier de plans. L’API est en lecture seule : elle ne modifie ni le dessin ni le projet.

Qui peut obtenir une clé API

L’accès à l’API est activé par l’exploitant, compte par compte. Une fois l’accès accordé à votre compte, la carte Clés API apparaît sur la page Profil ; sans cet accès, la carte reste masquée. Un compte peut avoir au plus 5 clés actives en même temps.

La clé voit les mêmes projets que vous : les vôtres et, sur demande, ceux qui ont été partagés avec vous. Pour un projet partagé, les listes et le métré ne sont fournis que si le partage autorise aussi l’export.

Créer une clé

Sur la carte Clés API de la page Profil, cliquez sur Nouvelle clé.
Donnez un nom à la clé (par exemple le nom du programme qui l’utilisera).
Choisissez la portée : Lire les projets donne la liste des projets et leurs données, Lire les documents donne les listes, le métré et le dossier de plans. Ne sélectionnez que ce dont le programme a réellement besoin.
Choisissez l’expiration : 30, 90 ou 365 jours. Une clé expirée ne fonctionne plus ; vous en créez alors une nouvelle.
Saisissez votre mot de passe actuel (pour un compte sans mot de passe, une connexion récente est nécessaire). Pour votre première clé, acceptez les conditions d’utilisation de l’API.

Après la création, la clé n’est affichée qu’une seule fois : copiez-la et conservez-la en lieu sûr. Ensuite, la liste n’affiche que son préfixe (avk_…), avec les dates de création et d’expiration, la dernière utilisation et le nombre d’appels. Nous envoyons aussi une notification par e-mail pour la nouvelle clé (sans la clé elle-même).

Révoquer une clé

Le bouton Révoquer à côté d’une clé la rend immédiatement inutilisable ; cette action est irréversible. Révoquez la clé quand vous ne l’utilisez plus, quand vous arrêtez le programme qui l’utilisait, ou si vous soupçonnez qu’elle a fuité.

Conseils de sécurité

Traitez la clé comme votre mot de passe : quiconque la connaît peut lire vos projets dans la limite de sa portée.
Conservez-la dans un coffre de secrets (gestionnaire de mots de passe, variable d’environnement du serveur ou variable secrète de la CI), pas dans le code source : ne la placez jamais dans un dépôt git, un tableur partagé ou un e-mail.
Ne l’utilisez pas dans du code exécuté dans un navigateur (page web, extension de navigateur) : n’importe qui peut l’y lire. Une clé a sa place sur un serveur, dans un script ou dans un programme de bureau.
Donnez à chaque programme sa propre clé, avec la portée la plus étroite possible et une expiration courte ; ainsi, révoquer une clé n’arrête rien d’autre.

Utilisation depuis un programme

La clé est envoyée dans l’en-tête de la requête comme jeton Bearer : Authorization: Bearer avk_…. Les points d’accès se trouvent sous /api/v1/ (par exemple GET /api/v1/projects) et répondent en JSON. La description complète au format OpenAPI est disponible à l’adresse /api/v1/openapi.json ; la plupart des outils de développement peuvent l’importer.

Le nombre d’appels est limité par clé et par compte (par défaut 60 par minute et 10 000 par jour) ; au-delà, le serveur répond par 429, patientez alors un peu. La connexion sur le site (cookie) n’ouvre pas l’API, et une clé ne vous connecte pas à l’interface web.