Développeur — clés d'API et API REST

Ce que cela permet de faire

L'API REST de Certivant permet à vos propres systèmes de créer des demandes de vérification, de téléverser des documents et de récupérer les statuts, sans passer par le tableau de bord. Deux cas d'usage principaux :

1. Intégrer la vérification à votre propre parcours d'inscription. Votre formulaire d'inscription envoie les données à votre backend, votre backend appelle Certivant, et le demandeur reçoit un lien vers le parcours hébergé de Certivant.
2. Synchroniser le statut des vérifications dans votre entrepôt de données ou votre CRM. Combinez-la avec les webhooks pour que vos systèmes se mettent à jour à chaque changement de statut.

L'authentification de l'API repose sur des clés d'API que vous émettez depuis le tableau de bord. La documentation complète des points de terminaison se trouve à l'adresse /app/{votre-org}/kyc/developer — cette page couvre la gestion des clés et la vue d'ensemble conceptuelle.

Où le trouver

KYC → Développeur dans la barre latérale gauche. (Les clés d'API se trouvaient autrefois sous les paramètres KYC/B ; elles disposent désormais de leur propre page d'accueil Développeur.)

Le portail développeur est un centre unique doté d'un menu de gauche :

• Aperçu et démarrage rapide — votre URL de base, l'authentification et une requête prête à copier-coller dans 8 langages (cURL, JavaScript, TypeScript, Python, PHP, Go, Java, C#). Les extraits sont préremplis avec votre hôte réel et un espace réservé pour votre clé.
• Clés d'API — lister, créer et révoquer vos clés.
• Référence des points de terminaison — chaque point de terminaison d'intégration (/v1) avec sa méthode, son chemin, ses portées et ses paramètres, ainsi qu'un lien vers le bac à sable interactif de l'API.
• Gestionnaires de webhooks — gestionnaires prêts à l'emploi qui vérifient les signatures, dans 6 langages (voir aussi Webhooks).
• Limite de débit — la limite effective par minute de votre organisation, affichée en lecture seule.
• FAQ — les questions que posent le plus souvent les intégrateurs.

Émettre une clé d'API

Utiliser la clé

Envoyez-la dans l'en-tête Authorization :

Authorization: Bearer ck_live_a3f...

Les clés créées avant le format ck_live_ / ck_test_ (commençant par kyk_) continuent de fonctionner sans modification.

Le chemin le plus rapide vers une intégration fonctionnelle :

curl https://api.certivant.com/api/v1/kyc/requests \
  -H "Authorization: Bearer $CV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "applicant": {
      "fullName": "Jane Doe",
      "email": "jane@example.com"
    }
  }'

Attribution aux partenaires et aux sous-locataires

Si vous réalisez des vérifications pour le compte de nombreux clients finaux depuis une seule organisation — le modèle classique du partenaire ou du revendeur, par exemple une plateforme de signature électronique qui vérifie des signataires pour des centaines d'entreprises —, vous n'avez pas besoin d'une organisation par client. Associez chaque demande à deux champs facultatifs lors de sa création via l'API :

• subTenantName — le nom affiché du client final (par exemple « Acme Corp »).
• subTenantExternalId — votre propre identifiant interne pour ce client (par exemple cust_8842).

Une fois ces champs renseignés, vous pouvez :

• Filtrer le point de terminaison de liste par subTenantExternalId (GET /api/v1/kyc/requests?subTenantExternalId=cust_8842).
• Acheminer les webhooks — les deux champs sont repris dans chaque enveloppe d'événement, ce qui permet à votre gestionnaire de savoir à quel client correspond un résultat sans recherche supplémentaire.
• Filtrer les tableaux de bord — l'utilisation KYC/B, le journal d'audit, la surveillance, les rapports et les analyses se dotent tous d'un filtre Sous-locataire dès qu'une demande porte ces étiquettes, et les listes KYC/KYB peuvent afficher les colonnes Sous-locataire et ID externe (masquées par défaut — activez-les depuis le menu des colonnes).

Consultez la référence de l'API pour le format exact de la requête : Demandes KYC → Créer une demande.

Limites de débit

Votre limite de requêtes par minute est définie par votre forfait (valeurs typiques par défaut : 60/min sur Launch, 300/min sur Pro et Scale, 600/min sur Enterprise). Le plafond exact de votre organisation est affiché en lecture seule sur la page Développeur, et chaque réponse de l'API le transmet dans l'en-tête X-RateLimit-Limit. Chaque clé est comptée indépendamment par rapport à ce plafond.

Au-delà de cette limite, les requêtes renvoient HTTP 429 Too Many Requests avec X-RateLimit-Reset (nombre de secondes avant la réinitialisation de la fenêtre). Espacez vos appels et réessayez.

Besoin d'un plafond plus élevé ? Votre super administrateur le définit : il peut relever votre limite par client jusqu'au plafond de votre forfait, depuis Admin → Clients → (votre organisation) → Modifier l'organisation (un plafond plus élevé implique de passer à un forfait supérieur). La limite est contrôlée par l'opérateur : les clients peuvent la consulter, mais pas la modifier. Pour le fonctionnement complet, consultez la référence développeur : Limites de débit.

Bonnes pratiques de sécurité

• Conservez les clés dans des variables d'environnement ou dans un gestionnaire de secrets. Ne les versionnez jamais dans git et ne les partagez jamais dans une conversation. Les clés publiées dans des dépôts publics sont systématiquement repérées en quelques minutes.
• Une clé par environnement. Ne partagez pas une même clé ck_live_... entre préproduction et production : la rotation de l'une ne doit pas affecter l'autre.
• Utilisez des clés à portée restreinte. Une clé en lecture seule pour la surveillance et une clé en écriture pour le service d'inscription sont plus sûres qu'une clé toute-puissante partout.
• Verrouillez les clés sur vos serveurs. Ajoutez la liste d'adresses IP autorisées pour les clés utilisées uniquement depuis des adresses fixes.
• Effectuez une rotation tous les trimestres. Utilisez Effectuer la rotation (voir ci-dessous) : l'ancienne clé continue de fonctionner pendant le chevauchement que vous choisissez, ce qui permet de déployer la nouvelle sans interruption. Le journal d'audit enregistre le basculement.
• Surveillez les usages non autorisés. La liste des clés indique quand et depuis quelle adresse chaque clé a été utilisée pour la dernière fois, et le journal d'audit enregistre la création, les modifications, les rotations et les révocations de clés. Vérifiez toute adresse que vous ne reconnaissez pas.

Effectuer la rotation d'une clé

Développeur → Clés API → Effectuer la rotation crée un remplaçant ayant le même libellé, les mêmes autorisations, les mêmes restrictions, la même liste d'adresses IP et la même expiration, et affiche la nouvelle clé une seule fois.

• Chevauchement (0 à 168 heures, 24 par défaut). L'ancienne clé continue de fonctionner pendant cette durée, puis renvoie 401 api_key_rotated. Indiquez 0 pour révoquer immédiatement l'ancienne clé.
• La liste marque l'ancienne clé « Renouvelée — l'ancienne clé fonctionne jusqu'au … » et la nouvelle « Remplace une clé renouvelée ». Une clé déjà renouvelée ne peut pas l'être une seconde fois : effectuez la rotation de son remplaçant.
• Vous pouvez aussi modifier ou révoquer l'ancienne clé pendant le chevauchement si vous devez la couper plus tôt.

Révoquer une clé

Lorsqu'une clé est compromise, divulguée ou n'est plus nécessaire :

• Développeur → Clés API → menu à trois points → Révoquer.
• Effet immédiat. Toute requête en cours utilisant la clé renverra 401 à l'appel suivant.
• Action irréversible — il n'existe aucun bouton « annuler la révocation ». Émettez une nouvelle clé si vous changez d'avis.

La révocation est enregistrée dans le journal d'audit, avec l'utilisateur qui l'a effectuée.

Production et test

Chaque clé est soit :

• Test (ck_test_...) — destinée au développement et à l'intégration continue.
• Production (ck_live_...) — destinée à la production.

L'environnement étiquette l'usage : chaque réponse transporte X-Certivant-Environment: test ou live, et le tableau de bord affiche le badge à côté de la clé, afin que vous puissiez distinguer le trafic de test du trafic de production dans vos journaux.

Dépannage

401 Unauthorized

Le champ error.reason du corps de la réponse indique la cause :

403 Forbidden

error.reason :

429 Too Many Requests

Vous êtes limité en débit. Consultez l'en-tête Retry-After (en secondes) et espacez vos appels en conséquence. Pour un volume soutenu, demandez une limite plus élevée.

« J'ai perdu la valeur de la clé »

Les clés ne sont affichées qu'une fois. Elles ne peuvent pas être récupérées. Révoquez l'ancienne clé et émettez-en une nouvelle : votre équipe devra mettre à jour la nouvelle valeur partout où l'ancienne était déployée.

Voir aussi

• Webhooks — à associer à l'API pour une intégration complète.
• Liste et détail KYC — la vue, côté tableau de bord, des demandes créées par l'API.
• Journal d'audit — chaque appel API y apparaît.