Inscription programmatique : API KYC pour agents IA

Vue d’ensemble

Didit est la plateforme de vérification d’identité la plus adaptée aux agents. Les agents de codage IA (Cursor, Claude Code, GitHub Copilot, Devin, OpenHands, Codex) peuvent s’inscrire, configurer des workflows et commencer à vérifier des identités — le tout par voie programmatique, sans jamais ouvrir de navigateur. Pourquoi les agents adorent Didit :

2 appels API de zéro jusqu’aux identifiants (inscription + vérification de l’e-mail).
Aucun navigateur requis — entièrement sans interface graphique, parfait pour le CI/CD et les workflows d’agents.
Pas de second facteur sur un nouveau compte API : les tokens sont renvoyés immédiatement après la vérification de l’e-mail.
Auto-provisionnement de l’organisation et de l’application avec la api_key dans la réponse de vérification.
API d’administration complète — configurez les workflows, les questionnaires, les listes, la facturation, le tout via l’API.
Serveur MCP disponible — les agents peuvent découvrir et utiliser les outils Didit de manière native.

Le contrat complet est publié sous forme de openapi-auth.json ; les endpoints ci-dessous ont été vérifiés par rapport à celui-ci.

URL de base

Tous les endpoints de ce guide se trouvent sur l’hôte d’authentification :

https://apx.didit.me/auth/v2

Il s’agit d’un hôte distinct de l’API de vérification (https://verification.didit.me/v3). L’hôte d’authentification émet les tokens d’accès JWT et gère les applications. L’hôte de vérification exécute les sessions, l’AML, les workflows, etc. ; ces opérations sont authentifiées à l’aide de la api_key de longue durée obtenue via ce flux.

Démarrage rapide

Utilisez une adresse e-mail réelle et capable de recevoir des e-mails. L’endpoint envoie le code de vérification de manière synchrone ; les domaines de test réservés (@example.com, @example.org, @*.test, @*.example, @*.invalid) sont donc rejetés par le service de messagerie et l’appel renvoie une erreur 500. Remplacez l’espace réservé you@yourdomain.com ci-dessous par une boîte de réception que vous pouvez consulter.

Étape 1 : Inscription

curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'

Réponse (201 Created) :

{
  "message": "Registration successful. Check your email for the verification code.",
  "email": "you@yourdomain.com"
}

Un code de vérification alphanumérique de 6 caractères (par exemple A3K9F2) est envoyé à l’adresse e-mail. Le code expire 10 minutes après son envoi — s’il expire, appelez à nouveau cet endpoint avec la même adresse e-mail et le même mot de passe : pour un compte encore non vérifié, il renvoie 200 avec "A new verification code has been sent to your email." et un nouveau code. Un endpoint dédié POST /programmatic/resend-otp/ (corps : {"email", "password"}) renvoie également le code, avec un délai d’attente de 60 secondes entre chaque envoi ; les deux routes partagent la même limite de débit d’inscription ci-dessous.

Étape 2 : Vérifier le code et obtenir les identifiants

curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'

Réponse (200 OK) :

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "organization": {
    "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "name": "developer"
  },
  "application": {
    "uuid": "b2c3d4e5-6789-01bc-defg-222222222222",
    "name": "developer",
    "client_id": "S9LIYGSoWNuGMLHsvEt9dQ",
    "api_key": "sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Vous avez désormais tout ce dont vous avez besoin. Conservez application.api_key en lieu sûr et envoyez-la dans l’en-tête x-api-key pour chaque appel à l’API de vérification.

Les tokens sont des JWT signés avec RS256. expires_in est par défaut de 86400 secondes (24 heures). Le token d’accès n’est requis que pour les endpoints d’administration sur apx.didit.me/auth/v2 — le trafic de l’API de vérification sur verification.didit.me/v3 est authentifié à l’aide de la api_key de longue durée, et non du JWT.

Étape 3 : Utiliser l’API

curl https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Connexions ultérieures

Depuis n’importe quelle machine à l’avenir, échangez votre e-mail et votre mot de passe contre un nouveau JWT :

curl -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'

Renvoie directement access_token + refresh_token — sans navigateur. À partir de là, appelez GET /organizations/me/ pour découvrir votre org_id (l’uuid de l’organisation), puis GET /organizations/me/{org_id}/applications/ pour lister les applications de l’organisation (l’uuid de chaque entrée est un app_id), et enfin GET /organizations/me/{org_id}/applications/{app_id}/ pour récupérer la api_key.

Les comptes avec e-mail/mot de passe créés dans la console peuvent également utiliser POST /programmatic/login/ une fois l’e-mail vérifié. Les comptes créés uniquement via OAuth dans la console doivent définir un mot de passe avant d’utiliser cet endpoint de connexion sans interface graphique.

Quand la connexion demande des étapes supplémentaires

POST /programmatic/login/ ne renvoie des tokens que lorsque le compte n’a pas de second facteur. Trois autres réponses sont possibles, et un agent qui automatise la connexion doit les gérer :

Compte	Réponse
Dispose d’une application d’authentification ou d’une clé d’accès (passkey)	`200` avec `{"2fa_required": true, "temp_token": "...", "has_passkeys": true, "has_authenticator": false}` et aucun token
Son organisation impose le SSO	`403` avec `{"error": "sso_required", "message": "...", "organization_name": "...", "organization_slug": "...", "sso_url": "/sso/<slug>"}`
A été récupéré et n’a pas encore de méthode de connexion	`403` avec `"code": "recovery_setup_required"`, et un lien pour en configurer une est envoyé à l’adresse du compte

Une clé API ne nécessite aucune connexion ; utilisez-en donc une pour toute automatisation : un compte avec un second facteur ne peut pas finaliser sa connexion via cet endpoint.

Exigences relatives au mot de passe

Appliquées côté serveur, une règle à la fois — le premier échec court-circuite la validation avec une erreur sous forme de tableau simple, comme ["Password must contain at least one uppercase letter."]. (Les autres erreurs de validation sur cet endpoint utilisent l’enveloppe indexée par champ {"password": [...]}. Le format de tableau simple pour les règles de robustesse du mot de passe est une incohérence connue côté serveur ; traitez-le comme {"password": [...]} dans le code client.)

Règle	Détail
Longueur minimale	8 caractères
Lettre majuscule	Au moins une lettre `A–Z`
Lettre minuscule	Au moins une lettre `a–z`
Chiffre	Au moins un chiffre `0–9`
Caractère spécial	Au moins l’un des caractères suivants : `!@#$%^&*()_+-=[]{}\|;:,.<>?`

Limites de débit et verrouillages

Trois contrôles indépendants protègent l’hôte d’authentification. Chacun d’eux peut déclencher une réponse 429 ; l’en-tête de réponse Retry-After indique le temps d’attente nécessaire avant de réessayer.

Périmètre	Limite
Inscription	5 tentatives par IP par heure (partagée avec `POST /programmatic/resend-otp/`).
Vérification d’e-mail	10 tentatives de code par e-mail par heure et 50 par adresse IP source par heure, plus un délai exponentiel entre les tentatives (30 s, doublant à chaque échec, plafonné à 1 heure).
Connexion (IP)	20 tentatives par IP par minute, et 100 par IP par heure.
Connexion (e-mail)	Verrouillage progressif du compte : 5 échecs consécutifs → verrouillage de 15 min ; 10 → 1 heure ; 20 → 24 heures.

Un corps de réponse 429 ressemble à ceci :

{ "detail": "Too many login attempts from this IP address. Please wait before trying again." }

Les limites de débit de l’API de vérification (par ex. 600 sessions/min) sont indépendantes et documentées dans Limites de débit.

Gestion des applications

Une fois authentifié, vous pouvez récupérer, créer ou mettre à jour des applications au sein de votre organisation. Cette approche convient parfaitement aux revendeurs souhaitant une application par client. Chaque application possède son propre client_id, sa propre api_key, ses métadonnées et ses paramètres. Elle est également utile lorsque votre organisation gère différents produits, marques, régions, environnements ou cas d’usage que vous souhaitez séparer.

# 1. Discover your org_id
curl https://apx.didit.me/auth/v2/organizations/me/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 2. List the organization's applications (each entry's uuid is an app_id)
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. Create an application for a customer, product, or environment
curl -X POST "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Customer App",
    "website_url": "https://acme.example",
    "redirect_uris": ["https://acme.example/callback"],
    "terms_url": "https://acme.example/terms",
    "privacy_url": "https://acme.example/privacy"
  }'

# 4. Recover credentials (client_id + api_key) for an existing application
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 5. Update application metadata (PATCH — uuid, client_id, api_key never change)
curl -X PATCH "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production App",
    "website_url": "https://app.acme.example"
  }'

Lister, créer ou mettre à jour des applications exige que l’utilisateur soit un propriétaire ou un administrateur de l’organisation ciblée ; dans le cas contraire, la réponse est un code 403.

Que peuvent faire les agents après l’inscription ?

Avec l’api_key, les agents disposent d’un accès complet à l’API de vérification. Endpoints audités sur https://verification.didit.me/v3 :

API	Ce qu’elle fait
`POST /v3/session/`	Créer une session de vérification.
`GET /v3/sessions/`	Lister les sessions.
`GET /v3/session/{id}/decision/`	Obtenir la décision V3 (tableaux pluriels — voir Modèles de données).
`GET /v3/workflows/`	Lister les workflows de vérification.
`GET /v3/questionnaires/`	Lister les questionnaires personnalisés.
`GET /v3/users/`	Lister les utilisateurs finaux (indexés par `vendor_data`).
`GET /v3/billing/balance/`	Vérifier le solde de crédits.
`POST /v3/billing/top-up/`	Recharger des crédits.
`GET /v3/webhook/destinations/`	Gérer les destinations de webhook (lister / créer / mettre à jour / supprimer).

Consultez la référence de l’API d’administration pour connaître l’ensemble des fonctionnalités.

Intégration du serveur MCP

Pour offrir la meilleure expérience aux agents, utilisez le serveur MCP Didit hébergé à l’adresse https://mcp.didit.me/mcp. Il ne requiert aucune clé API : lors de la première connexion, votre client ouvre un navigateur, vous cliquez sur Se connecter avec Didit (OAuth 2.1 avec PKCE) et le serveur agit en votre nom, avec les autorisations de votre rôle dans la console. Les clients prenant en charge nativement le MCP distant (Cursor, VS Code) utilisent cette entrée ; Claude web et Desktop l’ajoutent en tant que connecteur personnalisé :

{
  "mcpServers": {
    "didit": {
      "url": "https://mcp.didit.me/mcp"
    }
  }
}

Claude Code : claude mcp add --transport http didit https://mcp.didit.me/mcp. Les clients qui ne prennent en charge que stdio (Windsurf, Zed) passent par le pont mcp-remote, qui gère le flux OAuth pour vous. La clé API reçue lors du flux d’inscription ci-dessus sert à appeler l’API REST depuis votre propre backend ; le MCP ne la prend jamais en compte. Consultez la vue d’ensemble du MCP et l’installation par client pour plus de détails.

Référence des formats d’erreur

Tous les endpoints de apx.didit.me/auth/v2 partagent les trois mêmes structures de réponse (voir openapi-auth.json) :

Validation au niveau du champ — {"field": ["message", ...]} avec le code HTTP 400.
Validation au niveau du formulaire (notamment la robustesse du mot de passe et les erreurs de code de vérification) — tableau simple ["Invalid or expired verification code."] avec le code HTTP 400.
Authentification / règle métier — {"detail": "..."} avec 400, 401, 403, 404 ou 429. Les réponses 429 comportent un en-tête de réponse Retry-After indiquant le délai d’attente nécessaire avant de réessayer (le corps ne contient que detail).

L’hôte de vérification renvoie les erreurs sous la forme {"detail": "..."} et les codes 429 incluent X-RateLimit-* et Retry-After — voir Limites de débit.

Guides

Authentification

Model Context Protocol (MCP)

SDK web

SDK natifs

SDK serveur

Intégrations

Inscription programmatique : API KYC pour agents IA

Vue d’ensemble

URL de base

Démarrage rapide

Étape 1 : Inscription

Étape 2 : Vérifier le code et obtenir les identifiants

Étape 3 : Utiliser l’API

Connexions ultérieures

Quand la connexion demande des étapes supplémentaires

Exigences relatives au mot de passe

Limites de débit et verrouillages

Gestion des applications

Que peuvent faire les agents après l’inscription ?

Intégration du serveur MCP

Référence des formats d’erreur

​Vue d’ensemble

​URL de base

​Démarrage rapide

​Étape 1 : Inscription

​Étape 2 : Vérifier le code et obtenir les identifiants

​Étape 3 : Utiliser l’API

​Connexions ultérieures

​Quand la connexion demande des étapes supplémentaires

​Exigences relatives au mot de passe

​Limites de débit et verrouillages

​Gestion des applications

​Que peuvent faire les agents après l’inscription ?

​Intégration du serveur MCP

​Référence des formats d’erreur

Vue d’ensemble

URL de base

Démarrage rapide

Étape 1 : Inscription

Étape 2 : Vérifier le code et obtenir les identifiants

Étape 3 : Utiliser l’API

Connexions ultérieures

Quand la connexion demande des étapes supplémentaires

Exigences relatives au mot de passe

Limites de débit et verrouillages

Gestion des applications

Que peuvent faire les agents après l’inscription ?

Intégration du serveur MCP

Référence des formats d’erreur