Une clé par service sous Développeurs, Clés API, avec l'accès minimal et côté serveur. Renouvelez sans coupure et corrigez les erreurs 401 et 403.
Développeurs → Clés API, limité à l'application que vous avez sélectionnée. Chaque application possède une clé Principale, et vous pouvez en créer d'autres, une par service, chacune avec son propre accès et sa propre expiration. Une clé est un secret côté serveur : jamais dans du code frontend ni dans un bundle d'application.
Vos clés API se trouvent sous Développeurs → Clés API dans la console, limitées à l'application sur laquelle vous travaillez. Traitez chaque clé comme un mot de passe : elle donne un accès API 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 dans la carte d'application en haut de la barre latérale. Chaque application a ses propres clés.
- Ouvrez Développeurs, puis Clés API
L'onglet Clés liste toutes les clés, en commençant par la clé Principale, avec leur accès, leur dernière utilisation et leur date d'expiration.
#Créer une clé
Donnez à chaque service qui appelle Didit sa propre clé, pour voir ce que fait chacun et pouvoir le révoquer isolément.
- Cliquez sur Créer une clé
Sur Développeurs → Clés API.
- Nommez-la et choisissez l'environnement
Donnez à la clé le nom du service qui l'utilisera, choisissez Production (vérifications réelles, facturées) ou Sandbox (données de test, jamais facturées ; la clé est créée dans l'application Sandbox de votre organisation), puis choisissez quand elle expire : jamais, après 30 jours, 90 jours ou un an, ou à une date de votre choix.
- Choisissez son accès
Accès complet lit et écrit tout, pour votre propre backend. Lecture seule voit les sessions, les décisions et les médias mais ne peut rien modifier, pour un partenaire qui n'a besoin que des résultats. Personnalisé vous permet de choisir, ressource par ressource. Décochez Inclure les médias lorsque le service n'a besoin que de la décision, et pas des images de pièces d'identité, des selfies, des vidéos ou des rapports PDF.
- Vérifiez et copiez le secret
Le secret complet n'est affiché qu'une fois, à la création de la clé. Copiez-le directement dans votre gestionnaire de secrets.
La clé Principale est le secret d'origine de l'application. Elle a toujours un accès complet et peut être renouvelée, mais pas révoquée.
#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, autant que nécessaire |
| Secret de signature de webhook | Vérifier qu'un webhook entrant vient bien de Didit | Par endpoint de webhook |
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. Basculez la console sur Bac à sable et créez-y une clé, ou choisissez Sandbox comme environnement lorsque vous en créez une. Les sessions sandbox simulent chaque contrôle externe, ne sont jamais facturées et ne touchent aucune donnée utilisateur réelle.
Une clé appartient à une seule application, et donc à l'environnement de cette application : une clé sandbox ne crée jamais de vérification réelle, et une clé de production ne crée jamais de vérification sandbox. 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, ouvrez-la et choisissez Renouveler la clé. Vous obtenez un nouveau secret, et l'ancien continue de fonctionner pendant 24 heures, ce qui vous permet de déployer le nouveau secret sans interruption de service. Passé ce délai, toute requête avec l'ancien secret renvoie une erreur 401.
Si une clé doit cesser de fonctionner immédiatement, utilisez plutôt Révoquer la clé. La révocation l'arrête sur-le-champ et ne peut pas être annulée. La clé Principale peut seulement être renouvelée.
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, expirée, révoquée, ou a été renouvelée il y a plus de 24 heures | Vérifiez la clé sous Développeurs → Clés API pour cette application. Cherchez des espaces ou guillemets parasites, et vérifiez 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é de production (ou l'inverse), un accès qui n'a pas été donné à la clé (une clé en lecture seule qui tente d'écrire, par exemple), 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 utilisez plutôt l'une de ses clés. Détail complet : erreurs API et leur signification.
#Restreindre ce qu'une clé peut faire
Choisissez l'accès lors de la création de la clé, et modifiez-le plus tard avec Modifier l'accès (le secret reste le même ; l'accès de la clé Principale ne peut pas être modifié). Lecture seule empêche un partenaire de modifier quoi que ce soit, Personnalisé définit Aucun, Lecture ou Écriture par ressource (sessions, décisions, médias, personnes, entreprises et plus), et laisser Inclure les médias désactivé empêche un service de télécharger les images de pièces d'identité, les selfies, les vidéos et les rapports PDF. Sous Limites, une clé peut aussi être restreinte à certains workflows, aux seules sessions approuvées ou à une liste d'adresses IP : une requête venant d'une adresse hors de la liste reçoit une réponse 403, et une session hors des workflows ou des statuts de la clé reçoit une réponse 404. Ouvrez une clé pour voir exactement ce qu'elle peut faire ; une clé ne peut jamais faire plus que ce que son accès autorise.
#Qui, dans votre équipe, peut voir les clés
La visibilité des clés suit le rôle : voir la page nécessite l'autorisation de lire les clés API, que le rôle Développeur inclut. Les secrets restent masqués dans la console. 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 le Journal d'audit, attribuées à la clé plutôt qu'à une personne. C'est précisément pour cela qu'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.
Toujours bloqué ? Parlez à un humain.
Indiquez l'ID de votre organisation et l'ID de la session concernée.