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

# Authentification API : sécuriser les requêtes KYC

> Authentifiez les requêtes API Didit avec une clé dans l'en-tête x-api-key. Une clé invalide renvoie 401, une clé manquante renvoie 403.



Prompt d'authentification API
        Copier le prompt dans le presse-papiers



      
      

\<pre>

\````# Goal — authenticate against Didit's REST API

Two hosts, two auth schemes. Never mix them up.

\## Host map

\| Host | Surface | Auth header |
\|---|---|---|
\| `https://verification.didit.me` | Verification API — sessions, workflows, entities, transactions, standalone APIs, lists, webhooks, billing (every `/v3/...` route) | `x-api-key: <DIDIT_API_KEY>` |
\| `https://apx.didit.me` | Account / organization / application management (`/auth/v2/programmatic/...`, `/auth/v2/organizations/...`) | `Authorization: Bearer <JWT access_token>` |

The verification API does **not** use OAuth Bearer tokens. It uses a long-lived API key on the `x-api-key` header. Treat the key as a server-side secret — never ship it to a browser or mobile bundle.

\## How to obtain the api_key (no console UI needed)

\<Warning>
Substitute `you@yourdomain.com` below with a real inbox. The register endpoint sends the verification code synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get refused by mail delivery and the call returns a `500`.
\</Warning>

\```bash
\# 1) Register — emails a 6-char code (15 min TTL).
\#    Password rules: ≥8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special.
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "password": "StrongP@ss1"}'

\# 2) Verify email — returns api_key inline.
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
\# 200 -> { access_token, refresh_token, organization, application: { api_key, client_id, uuid } }
\```

Persist `response.application.api_key` as the env var `DIDIT_API_KEY`.
New keys start with `sk_live_` (live application) or `sk_test_` (sandbox application), followed by 43 URL-safe characters.
Keys created before this format have no prefix and keep working, so never validate a key by its prefix.

\## Recover the key (lost it)

\```bash
\# Log back in to get a fresh JWT
TOK=$(curl -s -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
-H "Content-Type: application/json" \
-d '{"email":"you@yourdomain.com","password":"StrongP@ss1"}' | jq -r .access_token)

\# Find your org and app
curl https://apx.didit.me/auth/v2/organizations/me/ -H "Authorization: Bearer $TOK"
curl https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/ \
-H "Authorization: Bearer $TOK"
\# Response.api_key is your key.
\```

\## Calling the verification API

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_id":"<WORKFLOW_ID>","vendor_data":"user-42","callback":"https://myapp.com/return"}'
\```

\## Failure modes

\| Status | Meaning | Fix |
\|---|---|---|
\| `401` on verification.didit.me | `x-api-key` header wrong, malformed, revoked or expired | Re-fetch via the recover-key flow above, or use a key that has not expired |
\| `403` on verification.didit.me | No `x-api-key` header, a scoped key without access to this resource or action, or a key called from an address outside its IP list | Use a key with that access (Developers -> API keys in the console) |
\| `403` with `"code": "application_deleted"` on verification.didit.me | The key's application was deleted. You get this for a few minutes after the deletion; after that the key is refused like any invalid key | Do not retry: the application and its keys no longer exist. Use a key of an application that exists |
\| `404` on a session route | The session is outside the scoped key's workflows or statuses | Use a key whose limits include that session |
\| `403` on apx.didit.me | JWT `Authorization` header missing or expired | Call `POST /auth/v2/programmatic/login/` again |
\| `429` | Rate limit; response includes a `wait` field (seconds) | Back off, then retry |

\## Sources of truth
\- /openapi-auth.json — every account / org / app endpoint
\- /openapi-25.json — every verification endpoint
\- /integration/integration-prompt — end-to-end integration recipe````

\</pre>



      
      

Coller dans

## Trouver votre clé APIDans Didit, les clés API sont restreintes à une **Application** spécifique au sein de votre compte. Une Application est un espace de travail dans lequel vous pouvez configurer des workflows et gérer des vérifications pour un projet ou un environnement particulier.Chaque Application reçoit une clé API principale disposant d'un accès complet lors de sa création. Vous pouvez ajouter d'autres clés à côté de celle-ci, chacune n'ayant que les accès dont un service ou un partenaire a besoin. Pour trouver vos clés :**1. Connectez-vous à la Business Console**Accédez à la [**Didit Business Console**](https://business.didit.me) et connectez-vous.**2. Sélectionnez votre Application**Choisissez l'**Application** avec laquelle vous souhaitez travailler dans le menu déroulant en haut.**3. Ouvrez les clés API**Accédez à **Développeurs -> Clés API** dans la barre latérale gauche.**4. Copiez ou créez une clé**La clé **Principale** est le secret propre à l'Application. Créez une nouvelle clé pour donner à un service ou un partenaire son propre secret, avec les accès dont il a besoin.> [!WARNING]
>
> **Votre clé API est un secret — traitez-la comme un mot de passe.**
>
> La clé principale offre un accès complet à l'API au nom de votre Application. Ne l'exposez jamais dans du code frontend, des dépôts publics ou des bundles côté client. Conservez-la toujours uniquement côté serveur.### Format de clé APILes nouvelles clés API commencent par `sk_live_` pour une application de production ou `sk_test_` pour une application sandbox, suivies de 43 caractères compatibles avec les URL (lettres, chiffres, `-` et `_`).
Les clés créées avant ce format n'ont pas de préfixe et continuent de fonctionner sans modification.
Envoyez la clé complète, préfixe inclus, dans l'en-tête `x-api-key`, et ne rejetez pas une clé au motif qu'elle n'a pas de préfixe.## Trouver l'ID de votre organisationVotre **ID de l’organisation** est l'UUID qui identifie votre organisation. Vous l'utilisez dans les chemins d'API restreints à l'organisation tels que `/auth/v2/organizations/me/{org_id}/applications/`. Vous pouvez le copier directement depuis la Business Console, sans aucun appel d'API nécessaire :**1. Ouvrez les paramètres de l'organisation**Dans la [**Didit Business Console**](https://business.didit.me), accédez à **Paramètres de l'organisation**.**2. Copiez l'ID de l'organisation**Le champ **ID de l’organisation** affiche l'UUID de votre organisation à côté du nom de l'organisation, avec un bouton permettant de copier l’UUID dans le presse-papiers.***## Effectuer des requêtes authentifiéesPour authentifier une requête API, incluez votre clé API secrète dans l'en-tête HTTP `x-api-key`.Voici un exemple de requête authentifiée vers l'endpoint `Create Session` :```shell cURL theme={null}
curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'
```***## Gestion des erreursSi votre clé API est incorrecte, mal formée ou révoquée, l'API renvoie `401 Unauthorized` :```json theme={null}
{
  "detail": "Authentication credentials were not provided or are invalid."
}
```Une clé expirée renvoie également `401`, avec `"detail": "This API key has expired."`.
Une requête sans clé renvoie `403` avec `"detail": "You do not have permission to perform this action."`.| Code d'état | Signification |
| - | - |
| **401** | La clé API est incorrecte, mal formée, révoquée ou expirée |
| **403** | Aucune clé API n'a été envoyée, la clé n'a pas accès à la ressource ou à l'action demandée, ou la requête provient d'une adresse située en dehors de la liste d'adresses IP de la clé |
| **403** avec `"code": "application_deleted"` | La clé appartient à une application qui a été supprimée. L'API renvoie cette réponse pendant quelques minutes après la suppression, puis refuse la clé comme n'importe quelle clé invalide. Ne réessayez pas : l'application et ses clés n'existent plus. |
| **404** | Sur une route de session : la session ne correspond à aucun des workflows ou statuts autorisés par la clé |La page [Erreurs d'API](https://docs.didit.me/fr/integration/api-errors.md) répertorie chaque statut, corps et code.***## Clés API avec restrictions de portéeDonnez à chaque service ou partenaire sa propre clé au lieu de partager la clé principale.
Chaque clé possède ses propres droits d’accès pour chaque ressource : aucun droit, lecture ou écriture (sessions, décisions, médias, personnes, entreprises, transactions, workflows, webhooks, paramètres de l'application, analyses), ainsi que des restrictions facultatives à certains workflows, aux sessions approuvées uniquement, à une liste d'adresses IP et à une date d'expiration.
Vous pouvez effectuer une rotation de clé avec un chevauchement de 24 heures, et la révoquer immédiatement.Les clés créées avant l'introduction des accès restreints conservent un accès complet.Consultez [Clés API](https://docs.didit.me/fr/console/api-keys.md) pour connaître les configurations prédéfinies, les ressources couvertes par chacune d'elles et la manière dont l'API répond à une clé restreinte.> [!TIP]
>
> Si vous recevez une erreur `401`, vérifiez bien que vous utilisez la bonne clé API pour la bonne Application et qu'elle n'a pas été régénérée.


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