KEPLIN Docs

APIs & GraphQL Clés d'API

Clés d'API

Générer, délimiter et révoquer des clés API — l'accès des systèmes externes au GraphQL de vos apps.

Les systèmes externes — un ERP qui synchronise des clients, un site qui crée des commandes, une intégration de facturation — appellent le GraphQL des apps avec une clé API : un secret envoyé dans le header x-api-key de chaque requête. Les clés sont gérées au niveau de la plateforme et partagées entre les apps : chaque clé a un scope — vous choisissez les apps et, par app, tous les endpoints ou seulement quelques-uns. Une intégration de facturation peut, par exemple, lire des comptes dans l'app Gestion des Clients et écrire des documents dans une autre app, avec une seule clé.

Nota

Les clés appartiennent à qui administre la plateforme : la page Clés API n'est disponible que pour les comptes administrateur.

La page Clés API

Ouvrez le menu Clés API dans la navigation globale. La liste montre toutes les clés de la plateforme :

Colonne Ce que c'est
Nom Le nom que vous avez donné à la clé — il identifie l'intégration.
Préfixe Les premiers caractères de la clé (ex. amk_A1b2C3…) — ils servent à reconnaître laquelle est laquelle sans jamais montrer la clé entière.
Scope Les apps auxquelles elle donne accès et, par app, « tous les endpoints » ou la liste de ceux qui sont accordés.
État actif ou révoquée.
Dernière utilisation Quand la clé a été utilisée pour la dernière fois — jamais, si elle ne l'a pas encore été.

La page Clés API, avec le scope et la dernière utilisation de chaque clé.
La page Clés API, avec le scope et la dernière utilisation de chaque clé.

Dica

La colonne Dernière utilisation est votre outil de ménage : une clé sans usage depuis des mois est candidate à la révocation.

Créer une clé API

  1. Cliquez sur Nouvelle clé API.
  2. Donnez un Nom de la clé — ex. intégration-facturation.
  3. Dans Scope — apps et endpoints autorisés, cochez les apps à inclure. Par défaut, chaque app cochée accorde « Tous les endpoints de cette app. »
  4. Pour resserrer l'accès dans une app, cochez Restreindre à des endpoints spécifiques et choisissez les APIs une par une. Dans une API de Table, l'octroi couvre toutes les opérations actives — la liste affiche « donne accès à : getContas, addContas, … » pour que vous sachiez exactement ce que vous accordez.
  5. Cliquez sur Générer la clé API.

La fenêtre de création d'une clé API, avec le scope par app et par endpoint.
La fenêtre de création d'une clé API, avec le scope par app et par endpoint.

Copier et conserver la clé

Après la génération, la fenêtre affiche la Clé en texte clair — une seule fois. Copiez-la avec Copier et conservez-la en lieu sûr (un gestionnaire de secrets, le coffre de votre équipe). Une fois la fenêtre fermée, vous ne la reverrez plus — la plateforme ne conserve pas la clé en clair ; si vous la perdez, vous ne pourrez que la révoquer et en générer une autre.

La clé générée, en texte clair pour la seule fois, avec le bouton Copier.
La clé générée, en texte clair pour la seule fois, avec le bouton Copier.

Atenção

Traitez la clé comme un mot de passe : ne la mettez ni dans du code source, ni dans des URL, ni dans des écrans d'utilisateur. Si vous soupçonnez une fuite, révoquez tout de suite — générer une nouvelle clé prend quelques secondes.

Utiliser la clé

La clé part dans le header x-api-key de chaque requête à l'endpoint GraphQL de l'app :

curl -X POST 'https://votre-hote/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -H 'x-api-key: amk_………' \
  -d '{"query":"query { getContas(take: 5) { id nome } }"}'

L'onglet Docs de chaque API génère cet exemple (et la variante JavaScript) avec la bonne opération — il ne manque que votre clé.

Ce qu'une clé voit et ne voit pas :

  • Seulement les APIs publiées — jamais les brouillons, même avec un scope d'app entière.
  • Seulement ce que le scope accorde : appeler une app hors du scope renvoie 403 — API key not authorised for this project ; appeler un endpoint hors du scope, 403 — API key not authorised for this endpoint.
  • Toujours la version principale de l'app (ou la version publiée de l'adresse utilisée) — jamais la version de travail d'un développeur.

Limites et erreurs

Chaque clé a un plafond de requêtes par minute. Les réponses d'erreur qu'une intégration doit savoir traiter :

Réponse Signification Que faire
401 Clé manquante, non valide, expirée ou révoquée. Vérifiez le header et l'état de la clé dans la liste.
403 Clé valide mais sans accès à l'app ou à l'endpoint. Ajustez le scope — générez une nouvelle clé avec le bon scope.
429 Plafond de requêtes par minute atteint. Attendez le temps indiqué dans le header retry-after et réessayez.

Révoquer une clé

  1. Dans la liste, cliquez sur l'icône de révocation de la ligne.
  2. Confirmez avec Révoquer la clé.

La révocation est immédiate : toutes les apps qui consomment cette clé perdent l'accès dès la requête suivante. Une clé révoquée ne peut pas être réactivée — elle reste dans la liste, marquée révoquée, comme trace.

Pourquoi ne… ?

  • J'ai perdu la clé — puis-je la revoir ? Non. La clé en clair n'est affichée qu'au moment de la création. Révoquez l'ancienne et générez-en une autre.
  • J'ai besoin de donner accès à un endpoint de plus — je modifie la clé ? Le scope se définit à la création. Générez une nouvelle clé avec le scope complet, remplacez-la dans l'intégration et révoquez l'ancienne.
  • Pourquoi l'intégration reçoit-elle un 403 sur un nouvel endpoint ? La clé a été restreinte à des endpoints spécifiques et le nouveau n'est pas dans la liste — même remède : nouvelle clé avec le bon scope.
  • La clé donne-t-elle accès aux écrans de l'app ? Non. Une clé ne parle qu'avec l'endpoint GraphQL. Les comptes d'utilisateurs de l'app sont autre chose, gérés dans les paramètres de l'app elle-même.