Gérer vos clés API
Trouvez votre clé API sous API & Webhooks dans la console, gardez-la côté serveur, utilisez une application sandbox distincte pour les tests, et corrigez les erreurs 401 et 403.
API & Webhooks, limité à l'application que vous avez sélectionnée. Une clé par application, et la clé est l'environnement : il n'y a pas de clé de test séparée sur une application live. C'est un secret côté serveur : jamais dans du code frontend ni dans un bundle d'application.
Votre clé API se trouve sous API & Webhooks dans la barre latérale de la console, limitée à l'application sur laquelle vous travaillez. Traitez-la comme un mot de passe : elle donne un accès API complet au nom de cette application.
#Trouver votre clé
- Connectez-vous à la Business Console
Rendez-vous sur business.didit.me et connectez-vous.
- Sélectionnez votre application
Choisissez l'application voulue dans le menu déroulant en haut de la console. Chaque application a sa propre clé.
- Ouvrez API & Webhooks
Votre clé API se trouve ici, aux côtés de vos destinations de webhook et de leurs secrets de signature.
- Create API key génère une nouvelle clé ; les clés sont par application.
- Le secret n'est affiché qu'une fois ici : copiez-le dans votre propre coffre de secrets.
- Rotate secret remplace le secret sans changer le nom de la clé.
- Last used permet de distinguer une clé active d'une clé oubliée avant de la révoquer.
#La clé API et le secret de signature sont deux choses différentes
Il vaut mieux le dire clairement, car les confondre produit des erreurs déroutantes :
| À quoi ça sert | Où | |
|---|---|---|
| Clé API | Authentifier vos appels vers Didit, dans l'en-tête x-api-key | Par application |
| Secret de signature de webhook | Vérifier qu'un webhook entrant vient bien de Didit | Par destination |
Envoyer le secret de signature comme clé API produit une erreur 401. Vérifier un webhook avec votre clé API produit une non-correspondance de signature. Les deux erreurs sont courantes.
Votre clé API est un secret. Ne la mettez jamais dans du code frontend, un dépôt public ou un bundle d'application mobile : gardez-la côté serveur uniquement. Une clé présente dans un bundle d'application livré est une clé qu'un attaquant possède. Voir authentification API.
#Obtenir une clé pour les tests
Vous ne testez pas en production. Créez une application distincte en mode sandbox : les sessions sandbox simulent chaque contrôle externe, ne sont jamais facturées, et ne touchent aucune donnée utilisateur réelle. Utilisez sa clé pendant que vous développez, et gardez une application live séparée pour les vraies vérifications.
Il n'existe pas de « clé de test » sur une application live. La clé est l'environnement, il vaut donc la peine de nommer vos clés sans ambiguïté partout où vous stockez vos secrets. Voir tester en sandbox.
#Faire une rotation de votre clé
Si une clé a pu être exposée, régénérez-la depuis la même page API & Webhooks. La régénération invalide l'ancienne clé immédiatement, donc mettez-la à jour partout où elle est utilisée avant de cliquer, sinon votre trafic de production commence à échouer au moment même où vous cliquez sur le bouton.
Faire une rotation régulière est une bonne pratique. Planifiez-la comme un déploiement, pas comme un simple clic.
#Corriger les erreurs 401 et 403
| Erreur | Cause | Correction |
|---|---|---|
401 | La clé est absente, malformée, ou a été régénérée | Copiez la clé actuelle depuis API & Webhooks pour cette application. Vérifiez l'absence d'espace ou de guillemets parasites, et que vous n'avez pas collé un secret de signature |
403 | La clé est valide mais cet appel n'est pas autorisé | Généralement la mauvaise application, un champ réservé au sandbox sur une clé live (ou l'inverse), une permission qui manque à votre clé, ou une fonctionnalité non activée sur votre compte |
Un 403 sur un workflow précis signifie presque toujours que la clé appartient à une application différente de celle qui possède ce workflow. Changez d'application dans la console et copiez sa clé à la place. Détail complet : erreurs API et leur signification.
#Restreindre ce qu'une clé peut faire
Si votre besoin est de limiter les catégories de données qu'une clé peut atteindre - par exemple pour empêcher un service de récupérer des images de document - c'est une question de permissions plutôt qu'un réglage de clé, et ce qui est disponible dépend de votre compte. Demandez au support plutôt que de supposer qu'une clé n'est pas restreinte, ou qu'elle l'est ; les deux suppositions sont risquées, dans des sens opposés.
#Qui, dans votre équipe, peut voir les clés
La visibilité des clés suit le rôle. Le rôle Developer couvre les clés API ; Reader non. Si un membre de l'équipe ne trouve pas la page, vérifiez son rôle avant de le signaler comme un bug. Voir inviter des membres et définir des rôles.
#Chaque appel est journalisé
Les requêtes par clé API apparaissent dans Audit Logs, attribuées à l'application plutôt qu'à une personne, ce qui est précisément la raison pour laquelle une clé partagée entre plusieurs services rend un incident plus difficile à investiguer. Une clé par consommateur est plus simple à raisonner. Voir utiliser les journaux d'audit.