> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Inscription programmatique : API KYC pour agents IA

> Obtenez vos identifiants Didit en 2 appels API sans navigateur. La plateforme de vérification d'identité pour Cursor, Claude et Devin.

## 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](https://docs.didit.me/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

> [!WARNING]
>
> **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

```bash theme={null}
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`) :

```json theme={null}
{
  "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

```bash theme={null}
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`) :

```json theme={null}
{
  "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.

> [!NOTE]
>
> 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

```bash theme={null}
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 :

```bash theme={null}
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`.

> [!NOTE]
>
> 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 :

```json theme={null}
{ "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](https://docs.didit.me/fr/integration/rate-limiting.md).

## 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.

```bash theme={null}
# 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](https://docs.didit.me/fr/sessions-api/management-api.md) 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é :

```json theme={null}
{
  "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](https://docs.didit.me/fr/integration/mcp/overview.md) et l'[installation par client](https://docs.didit.me/fr/integration/mcp/installation.md) 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](https://docs.didit.me/fr/integration/rate-limiting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.