Appearance
Clés API
Rôles requis
Administrateur ou SuperAdmin (gestion des clés).
L’onglet Source externe (bases de données externes) reste réservé au SuperAdmin.
Qu’est-ce qu’une clé API ?
Les clés API permettent à un système externe (par exemple l’outil BDD, un script d’intégration) d’appeler l’API formulaires de manière sécurisée, sans compte utilisateur.
Chaque clé est :
- rattachée à l’entreprise de l’administrateur qui la crée ;
- limitée par des scopes (permissions techniques) ;
- stockée de façon sécurisée (seul un préfixe est visible après création) ;
- révocable et expirable optionnellement.
Secret unique
Une seule valeur secrète est transmise au client technique : la clé brute affichée une seule fois à la création.
Elle doit être envoyée dans le header HTTP x-api-key.
Il n’y a pas de second « token » à fournir pour les appels machine-to-machine vers formulaires.
Accéder à la gestion des clés
- Se connecter avec un compte Administrateur ou SuperAdmin.
- Aller dans Paramétrage (route
/params/api-keys). - Ouvrir l’onglet Clés API.
Intégration outil BDD
La connexion depuis outil-bdd vers formulaires (FORMULAIRES_API_URL) est prévue dans un second temps. Aujourd’hui, les clés se génèrent et s’utilisent directement contre l’API formulaires.
Créer une clé
Depuis Paramétrage > Clés API, cliquer sur Nouvelle clé API.
| Champ | Description |
|---|---|
| Libellé | Nom d’usage (ex. « Intégration outil BDD ») |
| Scopes | Permissions accordées (voir ci-dessous) |
| Expiration | Date limite optionnelle, ou « Sans expiration » |
Scopes disponibles
| Scope | Usage |
|---|---|
forms:read | Lister les formulaires de l’entreprise (uuid, title, etc.) |
responses:export | Exporter les réponses d’un formulaire en CSV (et pièces jointes associées) |
cards:read | Lister les formulaires de l’entreprise (uuid, title, etc.) |
submissions:export | Exporter les réponses d’une fiche en CSV (et pièces jointes associées) |
Après validation :
- une notification confirme la création ;
- une fenêtre affiche la clé générée (une seule fois) ;
- un bouton Copier permet de la récupérer (avec confirmation après copie).
Conservation
Stockez la clé dans un coffre de secrets. Si elle est perdue, révoquez la clé et créez-en une nouvelle.
Liste, révocation et historique
- Afficher les clés révoquées : case à cocher dans la barre d’outils.
- Vue grille / tableau : bascule en haut à droite.
- Révoquer : menu « … » sur une clé active → confirmation.
- Voir les logs : historique des appels API (date, méthode, route, statut, IP).
Utilisation côté système externe
Authentification
Chaque requête sur les endpoints exposés doit inclure :
http
x-api-key: <votre_clé_complète>