Skip to main content
Chaque appel envoie la clé dans l’en-tête Authorization :
Une clé se compose de sk_, 8 caractères, un tiret bas et 64 caractères. Sahl ne conserve qu’un hachage SHA-256 de la clé et un préfixe (sk_a1b2c3d4) pour la liste de la console. Le secret est affiché une seule fois, à la création ou à la rotation de la clé, et personne chez Sahl ne peut le relire.

​
Créer une clé

  1. Connectez-vous à la console sur app.sahlfinancial.com en tant qu’administrateur de l’espace de travail ou gestionnaire d’API, avec une adresse e-mail vérifiée.
  2. Settings, puis API Keys, puis New key.
  3. Donnez-lui un nom, par exemple production-backend ou sandbox-test.
  4. Cochez les scopes. Seuls les scopes que votre espace de travail peut détenir sont proposés.
  5. Si vous le souhaitez, liez-la à un compte de service Google (voir plus bas).
  6. Create API Key. Copiez le secret depuis la bannière. Il n’est affiché qu’une fois.
Si le formulaire affiche « This workspace is not enabled for the partner KYC API, so its keys carry no scopes », demandez à Sahl d’activer l’API partenaire sur votre espace de travail. Une demande de création de clé avec un scope kyc: dans un espace de travail non activé renvoie 403 kyc_scope_not_allowed. Il n’y a pas de clé sandbox distincte d’une clé de production. Une même clé fonctionne dans les deux environnements. C’est le champ environment de chaque appel qui décide. Si vous voulez des clés différentes pour des systèmes différents, nommez-les et limitez leurs scopes en conséquence.

​
Scopes

  • Ces trois scopes sont les seuls. Un scope hors de cette liste est refusé à la création de la clé.
  • Une clé ne porte que les scopes avec lesquels elle a été émise, donc une clé divulguée pour un usage ne peut pas servir à un autre.
  • Chaque appel kyc: exige aussi que l’espace de travail soit activé pour l’API partenaire. Une clé qui détient le scope sur un espace de travail non activé reçoit 403 kyc_scope_not_allowed.
  • Donnez à chaque système le strict nécessaire. Un serveur qui ne fait que vérifier des profils a besoin de kyc:verify et non de kyc:extract, le scope qui consomme des lectures.

​
Renouveler une clé

La rotation émet une nouvelle clé et laisse l’ancienne fonctionner pendant une période de grâce, ce qui vous permet de déployer sans interruption.
  1. Settings, API Keys, repérez la clé, cliquez sur Rotate.
  2. Choisissez combien de temps l’ancienne clé continue de fonctionner : aucune période, 1 heure, 24 heures, 3 jours ou 7 jours. L’API accepte de 0 à 168 heures, 24 par défaut.
  3. Copiez le nouveau secret et déployez-le.
  4. Quand la période de grâce se termine, l’ancienne clé renvoie 401 API key expired.
Ce que le code garantit :
  • La nouvelle clé a le même nom, les mêmes scopes et le même compte de service lié que l’ancienne. La rotation ne peut ni élargir ni restreindre l’accès.
  • Renouveler une clé encore en période de grâce renvoie 409 key_already_rotated, donc une nouvelle tentative ne peut pas vous laisser avec plusieurs clés actives. Utilisez la clé successeur, ou créez-en une nouvelle.
  • Une rotation est une nouvelle attribution des scopes. Un espace de travail qui a quitté la liste d’autorisation des partenaires ne peut pas créer de nouvelles clés kyc: par rotation.
  • La liste des clés affiche « Grace » avec l’heure de fin pour une clé en période de grâce.

​
Révoquer une clé

Revoke dans la liste des clés. Une clé révoquée renvoie 401 Invalid or revoked API key dès l’appel suivant. Révoquez une clé qui a pu fuiter, puis créez-en une nouvelle. Une rotation sans période de grâce fait la même chose en une seule étape et vous donne une clé de remplacement.

​
Lier une clé à un compte de service

Si vos serveurs tournent sur Google Cloud, vous pouvez lier une clé au compte de service Google sous lequel ils s’exécutent. Chaque appel doit alors porter, dans X-Partner-Identity, un jeton d’identité signé par Google pour ce compte, émis pour l’audience indiquée dans le formulaire de la clé. Une clé divulguée seule est inutile. Le playground de l’API ne peut pas envoyer cet en-tête, donc ne liez pas une clé que vous voulez essayer dedans.

​
Erreurs

Pour corriger un scope manquant, créez une clé qui le possède. La vérification du scope passe avant celle de l’espace de travail, donc une clé sans le scope reçoit la forme en chaîne même si l’espace de travail n’est pas activé.

​
Garder les clés en sécurité

  • Appelez l’API depuis votre serveur uniquement. Ne mettez jamais une clé dans un navigateur, une application mobile ou un dépôt de code.
  • Conservez-la dans un gestionnaire de secrets ou une variable d’environnement comme SAHL_API_KEY.
  • Une clé par système, pour pouvoir en révoquer une sans arrêter les autres.
  • Surveillez Developers, Call log dans la console : les appels de chaque clé, leur statut et leur latence y sont listés, et la liste des clés indique quand chaque clé a appelé l’API pour la dernière fois.
  • Le playground de la documentation envoie la requête depuis votre propre navigateur directement à l’API Sahl. Ce site ne la relaie pas et ne stocke pas votre clé. Collez malgré tout une clé créée pour les tests, et révoquez-la quand vous avez terminé.