Authentification

Chaque requête adressée à l'API Certivant s'authentifie avec une clé d'API : un jeton Bearer de longue durée, limité à une seule organisation. Les sessions et les cookies servent au tableau de bord ; l'API ne les utilise jamais.

Format de l'en-tête

Authorization: Bearer ck_live_NjV3aXJWN0RpZ2tRZ1JLWEcxc1V2eEgwUjg...

• Le nom de l'en-tête est Authorization.
• Le schéma est Bearer (un espace, puis la clé).
• La clé commence par ck_live_ (production) ou ck_test_ (test). Les anciennes clés qui commencent par kyk_ continuent de fonctionner sans modification.

Chaque réponse d'un point de terminaison authentifié par clé contient X-Certivant-Environment: live|test. Les clés de test ne font que marquer l'utilisation ; elles n'isolent pas les données (voir Clés de production et de test).

Si la clé est absente, inconnue, révoquée, expirée ou remplacée par rotation, Certivant répond avec HTTP 401 et error.code = "UNAUTHORIZED". error.reason est un sous-code stable :

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "reason": "api_key_expired",
    "message": "This API key has expired. Create or rotate a key."
  }
}

D'où viennent les clés

Les clés d'API sont créées dans le tableau de bord, à KYC → Développeur. Vous devez être Propriétaire ou Administrateur de l'organisation. La clé n'est affichée qu'une seule fois, immédiatement après sa création : Certivant ne conserve qu'un haché SHA-256, nous ne pouvons donc pas la réafficher. Si vous la perdez, révoquez-la et créez-en une nouvelle.

Le tableau de bord liste chaque clé (par son préfixe de 8 caractères) avec ses portées, la date de sa dernière utilisation et son nombre d'utilisations. Vous pouvez révoquer une clé à tout moment ; la révocation est immédiate et irréversible.

Portées

Les portées sont cumulatives. Vous pouvez en accorder n'importe quel sous-ensemble lors de la création d'une clé. Une requête vers un point de terminaison dont vous ne détenez pas la portée requise renvoie HTTP 403 avec error.code = "FORBIDDEN" et error.reason = "insufficient_scope" ; le message énumère toutes les portées qui auraient été acceptées.

Portées standard

Portées par ressource

Pour appliquer le principe du moindre privilège, vous pouvez accorder à la place des portées <ressource>:<action>. Chacune est acceptée sur les points de terminaison de sa propre ressource en plus de la portée standard correspondante, et ne s'étend jamais au-delà de cette ressource.

Exemples : forms:write permet à une clé d'appeler POST /v1/kyc/forms/:formId/send sans pouvoir créer de demandes de vérification ; verifications:read + analytics:read forme une clé de tableau de bord en lecture seule. <ressource>:manage inclut toutes les autres actions sur cette ressource.

Restrictions

Outre les portées, une clé peut être restreinte lors de sa création ou de sa modification :

• Formulaires : la clé ne peut utiliser que les formulaires que vous choisissez, et n'atteindre que les vérifications créées par leur intermédiaire. Voir Restriction par formulaire.
• Workflows : la clé ne peut déclencher que les workflows d'automatisation (par nom) que vous choisissez. Voir Restriction par workflow.
• Liste d'adresses IP autorisées : adresses IPv4/IPv6 et plages CIDR (203.0.113.7, 198.51.100.0/24, 2001:db8::/32). Une requête provenant de toute autre adresse, ou dont l'adresse ne peut pas être déterminée, est refusée avec 403 ip_not_allowed.
• Expiration : après expiresAt, la clé renvoie 401 api_key_expired.

Toutes les restrictions sont vides (sans restriction) par défaut, et les clés existantes n'en ont aucune. Les clés créées avant l'existence des restrictions (kyk_…) et les jetons du connecteur ne sont jamais restreints.

Restriction par formulaire

Une clé restreinte aux formulaires X et Y est limitée à ces formulaires et aux vérifications créées par leur intermédiaire. Une vérification est « créée par un formulaire » lorsqu'elle a été envoyée avec POST /v1/kyc/forms/:formId/send (par n'importe quelle clé ou depuis le tableau de bord), soumise via le lien public du formulaire, ou créée avec POST /v1/kyc/requests et un formId.

Un renouvellement, ou une vérification UBO générée par une vérification d'entreprise, appartient au même formulaire que la vérification d'origine.

Restriction par workflow

Certivant ne dispose d'aucun point de terminaison qui désigne un workflow ; cette restriction ne produit donc aucun 403 sur un appel. Elle contrôle quels workflows d'automatisation peuvent s'exécuter pour les vérifications créées par la clé :

• Chaque vérification créée par la clé (POST /v1/kyc/requests, /requests/batch, POST /v1/kyc/forms/:formId/send, POST /v1/kyc/conferences avec un demandeur en ligne) enregistre la clé dont elle provient.
• À partir de là, pour cette seule vérification, seuls les workflows dont le nom figure dans la liste de la clé peuvent s'exécuter, quel que soit l'événement déclencheur : le demandeur qui soumet le formulaire, une décision, un réviseur, un webhook ou la clé elle-même. Les exécutions déclenchées par un événement pour tout autre workflow sont ignorées, de même qu'un workflow lancé par un autre workflow au moyen d'une étape Déclencher un workflow.
• La liste actuelle de la clé s'applique tant que la clé existe ; un resserrement ou une levée de la restriction prend donc effet immédiatement sur les vérifications en cours. Si la clé est supprimée, la liste qu'elle avait au moment de la création de la vérification continue de s'appliquer.
• Les vérifications créées depuis le tableau de bord, par un demandeur sur un formulaire public, ou par une clé sans restriction de workflow ne sont pas concernées, pas plus que tout autre déclencheur (planifications, autres vérifications).
• Un renouvellement, ainsi que les vérifications UBO d'une entreprise, héritent de la restriction de la vérification d'origine.

Le motif d'erreur workflow_not_allowed est réservé aux points de terminaison qui reçoivent un workflow par son nom ; aucun n'existe à ce jour.

Clés de production et de test

Les clés ck_live_… sont destinées à la production, et les clés ck_test_… au développement et à l'intégration continue. L'environnement est une étiquette, et non un bac à sable : les réponses contiennent X-Certivant-Environment, le tableau de bord affiche le badge, et les entrées d'audit enregistrent le préfixe de la clé. Mais une clé de test lit et écrit les mêmes données qu'une clé de production. Le seul bac à sable est celui au niveau du locataire : tant que Certivant n'a pas vérifié votre organisation, les fonctionnalités de vérification en direct sont bloquées pour toutes les clés. Utilisez une organisation distincte si vous avez besoin de données de test totalement séparées.

Bonnes pratiques pour les environnements

• Une clé par environnement. Créez des clés distinctes pour local, staging et production. Si vous compromettez un environnement, les deux autres restent protégés.
• Donnez à vos clés des libellés descriptifs. payments-service-prod-2026Q2 est préférable à key1. Le libellé apparaît dans le journal d'audit.
• Définissez une expiration pour les clés dont vous n'avez besoin que temporairement, pour les migrations, les démonstrations ou l'accès d'un tiers. Certivant rejette automatiquement la clé une fois expiresAt dépassée.
• Effectuez une rotation chaque année. Créez une nouvelle clé, basculez votre service sur celle-ci, puis révoquez l'ancienne une fois que la nouvelle a traité le trafic sans erreur.
• Ne versionnez jamais les clés dans git. Utilisez votre gestionnaire de secrets : AWS Secrets Manager, GCP Secret Manager, Doppler, Infisical, ou à tout le moins des fichiers .env listés dans .gitignore.

Rotation sans interruption

Utilisez Effectuer la rotation de la clé sur la clé (Développeur → Clés d'API), ou l'API :

POST /api/kyc/api-keys/{id}/rotate        (dashboard session, api.access permission)
{ "overlapHours": 24 }

sequenceDiagram
  participant You
  participant Dashboard
  participant Service
  participant Certivant
  You->>Dashboard: Rotate key (overlap 24 h)
  Dashboard-->>You: ck_live_new_… (same scopes, restrictions, IP allowlist)
  You->>Service: Deploy with new key in env var
  Service->>Certivant: Authenticated requests with new key
  Note over Certivant: Old key still works until the overlap ends
  Certivant-->>Service: Old key → 401 api_key_rotated after the overlap

1. Effectuez la rotation de la clé. La clé de remplacement reprend le libellé, les portées, les restrictions, la liste d'adresses IP autorisées et l'expiration ; sa valeur complète n'est affichée qu'une fois.
2. Déployez votre service avec la nouvelle clé pendant le chevauchement (de 0 à 168 heures, 24 par défaut). L'ancienne clé continue de fonctionner jusque-là, et son horodatage Dernière utilisation dans le tableau de bord indique si quelque chose l'appelle encore.
3. Une fois le chevauchement terminé, l'ancienne clé renvoie 401 api_key_rotated. Utilisez overlapHours: 0 pour la révoquer immédiatement. Vous pouvez aussi la révoquer manuellement plus tôt.

Que se passe-t-il lorsqu'une clé est révoquée

La requête suivante utilisant la clé révoquée renvoie 401. Il n'existe aucun délai de grâce. Si vous révoquez par erreur une clé dont vous avez encore besoin, créez-en une nouvelle : une révocation ne peut pas être annulée.

Points de terminaison publics (sans clé)

Un petit nombre de points de terminaison sont volontairement publics et n'exigent pas de clé d'API :

• GET /api/health et GET /api/status : sondes d'exploitation.
• GET /api/branding : configuration publique de l'image de marque pour l'interface hébergée.
• GET /api/kyc/public/status?ref=… : consultation du statut d'un demandeur par référence externe.
• GET /api/kyc/public/forms/:slug et les points de terminaison de soumission de formulaires : utilisés par l'interface de formulaire hébergée.

Ils sont documentés par souci d'exhaustivité, mais la plupart des intégrations ne les appellent jamais directement : l'URL de session hébergée gère toute l'interaction publique.

Journalisation d'audit

Chaque appel API authentifié est enregistré dans KycAuditLog avec le préfixe de la clé appelante, le point de terminaison et le type d'acteur (api). Vous pouvez consulter cette piste à KYC → Journal d'audit dans le tableau de bord. Les entrées d'audit sont conservées pendant toute la durée de vie de la demande à laquelle elles se rapportent.