Clés publiques et clés secrètes : les données de vérification ne sont pas accessibles au client.

Toden vous donne deux types de API clé, et la règle pour les utiliser est courte : la clé publiable (pk_) s'intègre à votre page web ou application mobile, et la clé secrète (sk_Une clé publique ne quitte jamais votre serveur. Elle permet de lancer une vérification et de lire un statut minimal, mais pas un nom, une date de naissance, un numéro d'identification ou un selfie. Une clé secrète, en revanche, permet de lire toutes ces informations.

Pour limiter la diffusion d'une clé divulguée, trois options s'offrent à vous : une liste blanche pour la clé (origines web pour une clé publique, adresses IP ou plages d'adresses pour une clé secrète), des clés par service afin qu'une révocation n'entraîne pas la paralysie de l'ensemble du service, et la révocation immédiate. La suite de cet article explique le fonctionnement de cette séparation et comment utiliser ces options avant d'en avoir besoin.

Pourquoi une vérification API Il vous faut deux types de clés ?

Car toute clé saisie dans un client finira par être lue par une personne non autorisée. Une application mobile peut être décompilée. Un fichier web peut être ouvert dans les outils de développement. Considérer une clé client comme secrète relève de l'espoir, pas de la garantie.

La conception part donc du principe que la clé du client peut fuiter et en limite les possibilités. Le tableau ci-dessous est extrait de la documentation d'authentification (s’ouvre dans un nouvel onglet) .

Une clé est composée de son préfixe suivi de 32 caractères alphanumériques aléatoires, par exemple :pk_test_aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xYLe préfixe indique d'un coup d'œil à un examinateur humain le périmètre et l'environnement qu'il examine, ce qui est utile lorsqu'une clé apparaît dans un journal ou une demande d'extraction.

Que peut-on faire avec une clé publique divulguée ?

Ils peuvent lancer des vérifications sur votre compte et consulter leur statut minimal. Ils ne peuvent pas lire le résultat d'une vérification, qu'elle soit la vôtre ou la leur, car le point de terminaison de résultat complet refuse une clé publiable.403 secret_key_required.

Cette limite est pertinente, mais elle n'est pas nulle. En production, chaque vérification effectuée est facturée sur votre solde créditeur, conformément à la documentation de l'environnement (s’ouvre dans un nouvel onglet) . Une clé publiable copiée sur un autre site web pourrait être utilisée pour exécuter des vérifications payantes. C'est ce risque que la liste blanche d'origine ci-dessous vise à réduire.

Que peut-on faire avec une clé secrète divulguée ?

Lire les données d'identité. Une clé secrète peut appelerGET /api/kyc/verifications/:idpour le résultat complet (données biométriques, numéro d'identification en clair, correspondance faciale) etGET /api/kyc/verifications/:id/media/:kindPour les selfies, les images de documents et les vidéos en direct. Il peut également interroger tous les points de terminaison de Risk Intelligence.

Considérez une clé secrète comme un mot de passe de base de données. Une fuite constitue un incident d'exposition de données pour votre organisation, et vos propres procédures de gestion des incidents ainsi que vos obligations légales s'appliquent. Ces dernières varient selon les juridictions, et cet article fournit des informations générales et non des conseils juridiques.

Où chaque élément clé doit-il se situer dans une intégration typique ?

Voici une forme courante pour une application d'intégration client :

1. L'application monte le Toden SDK avec une clé publiable . Le demandeur remplit les formulaires de consentement, de capture et de présence, et le SDK soumet la vérification.

2. L'application affiche un écran « Nous vérifions vos informations ». Si nécessaire, elle interroge le statut minimal via la clé publiable pour afficher la progression.

3. Votre système dorsal reçoit le webhook signé pour la vérification.

4. Votre système backend récupère le résultat complet à l'aide d'une clé secrète , met à jour la fiche client et décide de ce que l'application affichera ensuite.

Les données d'identité du demandeur transitent de l'appareil vers Toden et de Toden vers votre serveur. Il n'est jamais nécessaire qu'il revienne à l'appareil, et avec cette configuration, c'est impossible, car la seule touche présente sur l'appareil n'est pas autorisée à le récupérer.

Une erreur fréquente consiste à court-circuiter l'étape 4 en appelant le point de terminaison de résultat depuis l'application « uniquement pour l'écran de confirmation ». Cela nécessite une clé secrète sur l'appareil, ce qui compromet toute la conception. Il est préférable d'envoyer à l'application les quelques informations nécessaires depuis votre propre serveur.

Comment les environnements interagissent-ils avec les clés ?

Chaque clé appartient à un environnement, et les données ne passent jamais d'un environnement à l'autre.pk_test_Les clés fonctionnent contre Sandbox et unpk_live_Clé par rapport à la production. Les clés, les vérifications, les points de terminaison webhook et la configuration sont tous limités à un seul environnement.

L'utilisation d'une clé au mauvais endroit renvoie403 environment_mismatchLa règle pratique issue de la documentation est de conserver un seul environnement tout au long d'un flux : SDK Le support Sandbox de 's utilise unpk_test_une clé, et le backend qui lit ces résultats utilise unsk_test_clé.

Les clés de production dépendent également de votre profil d'entreprise. Jusqu'à la vérification de votre entreprise ( KYB ) est approuvé, les demandes de vérification de production et de téléchargement sont rejetées avecbusiness_not_approvedLe mode bac à sable fonctionne parfaitement.

Comment restreindre l'accès à une clé avant qu'elle ne soit divulguée ?

Dans le tableau de bord, sous Développeurs → API Chaque clé peut contenir une liste blanche. Le type de liste blanche dépend du périmètre d'application de la clé, car c'est dans ce périmètre que chaque contrôle s'applique.

Deux points découlent de ce tableau.

Tout d'abord, une liste blanche d'origine est un paramètre du navigateur. Il est utile de la configurer pour une intégration web, mais elle est inutile pour une application mobile, car une application native n'envoie aucune requête SQL.OriginPour les appareils mobiles, la limite concernant une clé publiable divulguée est sa portée, et non la liste blanche.

Deuxièmement, une liste blanche d'adresses IP est le moyen de contrôle le plus efficace pour protéger une clé secrète, et sa mise en place est peu coûteuse si votre infrastructure utilise des adresses de sortie fixes. Répertoriez les adresses IP publiques de sortie de vos serveurs. Si votre infrastructure ne dispose pas d'adresses de sortie fixes, il est important de le savoir avant de choisir l'emplacement de votre clé secrète.

Une liste blanche vide signifie que la clé fonctionne partout. La laisser vide est un choix, alors faites-le délibérément.

Que faire en cas de fuite d'une clé ?

Suivez ces étapes dans l'ordre :

1. Révoquer la clé dans Développeurs → API Clés . La révocation est immédiate : la prochaine requête avec cette clé sera rejetée.401.

2. Créez le remplacement avec le même périmètre et le même environnement, puis déployez-le. Pour une clé publiable dans une application mobile, cela implique une nouvelle version de l'application ; l'écart entre les étapes 1 et 2 est donc bien réel. Prévoyez-le.

3. Vérifiez votre journal d'audit. La création et la révocation de clés génèrent leapi_key.createdetapi_key.revokedDes webhooks permettent à vos outils de sécurité d'enregistrer qui a modifié quoi et quand.

4. Pour une clé secrète, évaluez les risques. Déterminez ce à quoi la clé pourrait accéder et pendant combien de temps, puis suivez votre propre procédure d'incident.

Si la clé n'a pas fuité et que vous effectuez une rotation planifiée, procédez en sens inverse des étapes 1 et 2 : créez et déployez d'abord la nouvelle clé, vérifiez que le trafic est bien redirigé, puis révoquez l'ancienne. La révocation en premier bloquerait toutes les requêtes intermédiaires.

Quelles habitudes permettent de limiter le rayon de l'explosion ?

• Une clé par service ou environnement. Si votre service d'intégration et votre fonction de reporting partagent une clé secrète, sa révocation entraîne l'arrêt des deux services. Des clés distinctes permettent de n'en révoquer qu'une seule.

• Les clés secrètes sont enregistrées dans un gestionnaire de secrets dès leur création. Chaque clé secrète n'est affichée qu'une seule fois. Par la suite, le tableau de bord n'affiche que son préfixe ; il n'y a donc rien à copier ultérieurement.

• Évitez de stocker les clés dans les dépôts. Une clé déposée dans un dépôt public doit être considérée comme divulguée, même si le dépôt est supprimé.

• Utiliser_test_Clés du développement et de l'intégration continue. Réserve_live_clés pour le trafic de production.

• Limitez les personnes autorisées à gérer les clés. La création ou la révocation d'une clé nécessite une autorisation spéciale.api_keys:createautorisation. Les membres qui ne l'ont pas voient les clés en lecture seule.

La règle à appliquer

Lors de l'analyse d'une intégration, posez-vous la question suivante pour chaque occurrence d'une clé : la personne qui utilise cet appareil ou qui lit ce paquet pourrait-elle utiliser cette clé pour accéder à des données d'identité ? Si la réponse est oui, même en dehors de vos serveurs, la conception est erronée, quelles que soient ses autres qualités.

Vérifiez ensuite trois points : la clé publique web est autorisée au niveau de l’origine, chaque clé secrète est autorisée au niveau de l’adresse IP lorsque votre infrastructure le permet, et votre équipe a répété la procédure de révocation et de remplacement. La documentation développeur détaille les points de terminaison accessibles par chaque clé, et la page de sécurité explique comment procéder. Toden gère les données de son côté.