Clés API
Les identifiants qu'utilisent vos serveurs, ce qui se passe quand vous en faites pivoter un, et comment voir ce qu'une clé a fait
Une clé API est le moyen par lequel votre backend prouve qu'il s'agit bien de vous. Les clés de test fonctionnent sur le sandbox ; les clés de production traitent de vrais demandeurs. Une clé appartient à un seul environnement et ne peut pas être utilisée dans l'autre.
Cette page s'adresse aux propriétaires et aux développeurs. Si votre équipe ne compte pas d'ingénieurs, vous ne l'ouvrirez probablement jamais.
En créer une
Nommez la clé d'après ce qu'elle va faire, confirmez avec un code de votre application d'authentification, et le secret s'affiche une seule fois.
Une seule fois, c'est une seule fois
Le secret n'est affiché qu'une fois, à la création. Nous ne conservons aucune copie que nous pourrions vous montrer à nouveau. Placez-le directement là où votre application conserve ses secrets. S'il est perdu, faites pivoter la clé et déployez la nouvelle.
Dans la vue combinée Tous les environnements, la fenêtre vous oblige à choisir l'environnement auquel appartient la clé, car rien ne permet de le déduire.
Lecture et écriture, ou lecture seule
La fenêtre de création demande aussi ce que la clé a le droit de faire. Lecture et écriture est la valeur par défaut, et c'est ce que sont toutes les clés que vous avez déjà. Lecture seule crée une clé à laquelle toute écriture est refusée, quoi qu'on lui accorde par ailleurs, pendant toute la durée de vie de la clé.
La lecture seule ne dit rien de la quantité de données qu'une clé peut lire. C'est la question suivante de la fenêtre, et les deux sont indépendantes : une clé en lecture seule peut être limitée aux résultats, et une clé en lecture et écriture peut tout lire.
Utilisez la lecture seule pour tout ce qui consulte vos données sans les modifier : un rapport, un tableau de bord interne, un export nocturne vers vos propres systèmes, un outil avec lequel votre équipe d'assistance recherche des clients. Donnez-la à un prestataire qui construit une intégration, et il ne pourra ni trancher un dossier ni modifier un réglage par accident.
Ce choix ne peut pas être modifié ensuite
La lecture seule est fixée pour toute la durée de vie de la clé. Il n'existe aucun moyen de l'élargir ensuite, et c'est voulu : une clé en lecture seule que l'on pourrait basculer ne serait pas une clé que l'on peut confier puis oublier. Si elle doit écrire, créez une nouvelle clé et révoquez l'ancienne.
Les clés en lecture seule sont signalées comme telles dans la liste, pour que vous voyiez d'un coup d'œil lesquels de vos identifiants peuvent modifier quoi que ce soit. Les clés en lecture et écriture ne portent aucun signe, puisque c'est le cas ordinaire.
Ce que cette clé peut lire
La troisième question de la fenêtre de création détermine quelle part d'une vérification la clé peut voir.
Résultats seuls est la valeur par défaut, et c'est ce que sont toutes les clés que vous avez déjà. Elle lit le statut, le verdict, les codes de motif et le résultat de chaque contrôle. Elle ne peut pas lire la personne : ni nom, ni date de naissance, ni numéro de document, ni images.
Données complètes ajoute tout cela. L'identité que nous avons lue sur le document, y compris
l'orthographe dans l'écriture d'origine et les dates exactement telles que la carte les imprime, ainsi
que les images capturées du document et du selfie. Votre intégration les demande appel par appel, avec
include=applicant,documents sur une vérification, si bien qu'une clé qui en dispose renvoie
toujours le simple résultat, sauf si vous demandez davantage.
Choisissez les données complètes quand l'un de vos outils a besoin de la personne et pas seulement de la réponse : une fiche client dans votre propre outil d'assistance, une synchronisation nocturne vers vos systèmes, un dossier de conformité. Associez-les à la lecture seule, et cet outil peut tout voir sans rien pouvoir modifier.
Les portées sont fixées à la création
Une clé ne peut pas obtenir les données complètes plus tard, et faire pivoter une clé conserve les
portées qu'elle avait déjà. Si une clé renvoie 403 quand votre intégration demande les données du
demandeur, c'est qu'elle a été créée en résultats seuls, et la solution est une nouvelle clé, pas un
pivotement. Créez-en une, mettez-la en place, et révoquez l'ancienne quand plus rien ne l'utilise.
Les clés qui disposent des données complètes sont signalées Identité dans la liste, pour que vous voyiez d'un coup d'œil lesquels de vos identifiants peuvent lire une vraie personne.
Les clés que nous émettons pour vous
Une chose à laquelle une clé peut accéder n'est toujours jamais accordée par défaut et ne peut pas être ajoutée à une clé que vous créez vous-même. Demandez-la-nous et nous l'émettons sur votre compte, où elle apparaît dans cette liste comme n'importe quelle autre.
Back office signale une clé capable d'ouvrir une session en agissant au nom de l'une de vos propres personnes, ce sur quoi repose la connexion de votre propre back-office. La clé ouvre la porte ; ce que la personne de l'autre côté peut réellement faire est déterminé par son poste sur la page Équipe, et par rien qui concerne la clé. Associez-la à la lecture seule, et leurs agents peuvent traiter votre file sans pouvoir rien trancher.
Une clé back-office a besoin de postes associés
Chaque échange nomme une personne, par l'identifiant que vous utilisez pour elle, et nous le
résolvons à partir de l'identifiant back-office défini sur le propre poste de cette personne, sur la
page Équipe. Associer un collègue n'autorise pas une requête qui en nomme un autre : chaque personne au
nom de laquelle votre back-office agit a besoin de son propre poste associé, et un identifiant non
associé est refusé avec NO_SEAT_FOR_EXTERNAL_ID alors que la clé elle-même s'authentifie
parfaitement. Cela ressemble à un identifiant défectueux, mais n'en est pas un.
Faire pivoter et révoquer
Pivoter émet un nouveau secret pour la même clé. Révoquer désactive la clé immédiatement, et toute intégration qui l'utilise encore commence à échouer dès l'appel suivant. Aucune des deux opérations ne peut être annulée, et toutes deux demandent d'abord votre code d'authentification, car une clé, c'est un accès à la production contenu dans une chaîne de caractères.
La confirmation pour une clé de production le dit en toutes lettres. Lisez-la avant de l'accepter.
Dernière utilisation, et ce qu'une clé a fait
La liste indique quand chaque clé a été utilisée pour la dernière fois, c'est-à-dire l'appel API le plus récent que nous avons enregistré pour elle dans l'environnement que vous consultez. Les appels d'une clé de production sont enregistrés en production : si la colonne semble vide, vérifiez le sélecteur d'environnement avant de conclure que la clé est inactive.
Sélectionnez une clé et un panneau affiche son trafic récent. Il est tiré des journaux d'intégration, si bien qu'un rôle sans accès aux Journaux voit la clé mais pas son historique, et le panneau le dit plutôt que d'afficher un graphique vide.
Si une clé n'a fait aucun appel, le panneau le dit aussi. Chaque appel authentifié que votre backend signe avec elle apparaît en quelques secondes.
Un peu d'entretien utile
Donnez à chaque intégration sa propre clé plutôt que d'en partager une, pour que la révocation d'un identifiant compromis ne mette pas hors service tout ce que vous faites tourner. Nommez les clés d'après le système qui les détient. Et n'oubliez pas que créer une clé ne l'abonne à rien : les vérifications créées avec une nouvelle clé n'atteignent vos points de terminaison que si un point de terminaison webhook est configuré pour les recevoir, ce dont la page des webhooks vous avertit directement.