API, clés & accès développeur
Ce que vous allez apprendre
Dans cette page vous apprendrez à lister, créer et révoquer des clés API (nom, description, expiration), à authentifier vos requêtes via X-API-KEY ou Bearer, à utiliser les utilitaires/middleware serveur fournis pour valider l’accès, à accéder à la documentation API depuis l’interface, à récupérer l’heure serveur pour tester et à essayer les endpoints de preview/diagnostic. Cette page est conçue pour un public non technique — suivez les étapes simples.
Aperçu rapide
Gestion des clés
Lister, créer (nom, description, expiration optionnelle) et supprimer vos clés API depuis Paramètres > API Keys.
Authentification simple
Utilisez X-API-KEY ou Authorization: Bearer <clé> dans les en-têtes HTTP pour appeler l’API.
Outils serveur
Un utilitaire et un middleware pour valider les clés : server/utils/auth/apiKeyUtils.ts et server/utils/auth/apiKeyAuth.ts.
Docs & utilitaires
Accédez à la documentation API depuis l’UI et testez les endpoints utilitaires (/api/server-time, endpoints de preview/diagnostic).
Composants front réutilisables
Dialogs, loaders, useTheme, useLanguage, et autres helpers pour intégrer et tester rapidement.
Sécurité & bonnes pratiques
La clé est affichée une seule fois lors de la création — copiez-la immédiatement et révoquez-la quand elle n’est plus nécessaire.
Étapes principales
1 — Lister vos clés API
Ouvrez l’interface : Paramètres > API Keys. Vous verrez la liste des clés créées (nom, description, date d’expiration). Si vous n’en avez pas, la liste sera vide.
2 — Créer une nouvelle clé
Cliquez sur “Créer une clé” (ou “New API Key”), remplissez :
- Nom : exemple “Intégration site web”
- Description : usage prévu
- Expiration (optionnelle) : choisissez une date si vous voulez qu’elle expire automatiquement
Après création, la clé vous est affichée UNE SEULE FOIS : copiez-la et stockez-la en lieu sûr (ex. gestionnaire de mots de passe).
3 — Révoquer / supprimer une clé
Dans la liste, sélectionnez la clé à révoquer et cliquez sur “Supprimer” -> confirmez. La suppression est immédiate et la clé ne fonctionnera plus.
4 — Utiliser la clé dans une requête (X-API-KEY)
Ajoutez l’en-tête X-API-KEY à vos requêtes HTTP. Exemple cURL :
curl -H “X-API-KEY: VOTRE_CLE_ICI” https://votre-domaine/api/endpoint
ou en JS (fetch) :
fetch(‘/api/endpoint’, { headers: { ‘X-API-KEY’: ‘VOTRE_CLE_ICI’ } })
5 — Utiliser la clé en Bearer token
Vous pouvez aussi envoyer la clé comme Bearer via l’en-tête Authorization :
curl -H “Authorization: Bearer VOTRE_CLE_ICI” https://votre-domaine/api/endpoint
Les deux méthodes sont prises en charge par notre système d’authentification.
6 — Tester l'heure serveur (debug/sync)
Pour vérifier la synchronisation horaire ou déboguer, appelez :
GET /api/server-time
Cela retourne l’heure du serveur — utile pour comparer à l’heure locale et vérifier les expirations de clés.
7 — Accéder à la documentation API depuis l'UI
Ouvrez Paramètres > API Docs. Vous y trouverez :
- Exemples d’appels (cURL, fetch)
- Liste des endpoints (y compris utilitaires/preview/diagnostic)
- Schémas de données et codes de réponse
8 — Tester les endpoints de preview/diagnostic
Depuis la doc ou via cURL, testez les endpoints utilitaires (par ex. /api/preview, /api/diagnostic et /api/server-time) pour vérifier les réponses et les headers.
9 — Intégrer la validation côté serveur (développeur)
Si vous travaillez avec un développeur ou l’équipe technique, utilisez les fichiers fournis :
- server/utils/auth/apiKeyUtils.ts — fonctions pour vérifier, lister et gérer métadonnées des clés
- server/utils/auth/apiKeyAuth.ts — middleware/handler pour valider X-API-KEY / Authorization: Bearer dans les requêtes entrantes Demandez à votre développeur d’ajouter ce middleware aux routes qui doivent être protégées.
Astuce pratique
La clé est affichée une seule fois à la création : copiez-la immédiatement. Utilisez des noms et descriptions explicites (ex. “Site marketing — lecture seule”) pour savoir rapidement à quoi sert chaque clé.
Erreur fréquente à éviter
Ne partagez pas votre clé dans des espaces publics (GitHub, forums, captures d’écran). Si une clé est exposée, révoquez-la immédiatement depuis Paramètres > API Keys et créez-en une nouvelle.
Exemples rapides
-
En-tête X-API-KEY :
- X-API-KEY: abc123…
-
En-tête Bearer :
- Authorization: Bearer abc123…
-
Vérifier l’heure serveur :
- GET /api/server-time
Où trouver quoi
- Créer / supprimer clés : Paramètres > API Keys
- Docs API : Paramètres > API Docs
- Utilitaires serveur : server/utils/auth/apiKeyUtils.ts
- Middleware d’auth : server/utils/auth/apiKeyAuth.ts
Mentions spéciales
Les composants front fournis (Dialogs, loaders, useTheme, useLanguage, useAuthProviders) facilitent la création d’interfaces de test (ex. dialog pour créer une clé) et la persistance des préférences (thème/langue). Si vous testez en local, l’alias-loader.mjs simplifie la résolution d’import pendant le build/dev.
Prêt à tester vos clés ?
Ouvrez Paramètres > API Docs pour essayer des appels en direct et voir des exemples adaptés à votre compte.
Next steps
- Si vous avez besoin d’aide pour diagnostiquer des problèmes d’authentification ou d’expiration : passez à la page suivante “Diagnostics, tokens & dépannage”.
- Si vous êtes développeur, demandez l’ajout du middleware server/utils/auth/apiKeyAuth.ts aux routes sensibles.
- Pensez à documenter les usages de chaque clé dans votre équipe et à mettre en place une rotation régulière des clés pour plus de sécurité.
(Page 10 de 11)