Documentation client

Documentation d'intégration à destination des équipes techniques. Elle décrit l'authentification, le modèle de vérification et les quatre services exposés par l'API Blink ID, ainsi que les SDK mobile et web.

Ce document sert de base au futur site de documentation.

1. Vue d'ensemble

Blink ID fournit la vérification d'identité en Afrique à travers un jeu unique d'API et de SDK. Vous pouvez vérifier une personne à partir d'un numéro d'identité, d'un document d'identité ou d'un contrôle biométrique par selfie, et cribler un profil contre les listes de fraude. Choisissez le service qui correspond à votre parcours d'inscription.

Quatre services sont disponibles :

2. Environnements

Deux environnements strictement séparés. Une clé émise dans l'un ne fonctionne pas dans l'autre.

Les exemples de ce document utilisent l'URL de production.

3. Authentification

3.1 Clé d'API

Chaque client reçoit un identifiant partenaire (partner_id) et une clé d'API (api_key), disponibles dans le tableau de bord, section Développeurs → Clés d'API.

La clé d'API ne sert jamais à appeler directement un service de vérification. Elle sert uniquement à générer un token d'accès.

Ne publiez jamais votre clé d'API côté client. Elle doit rester sur votre serveur, dans une variable d'environnement. Une clé exposée dans une application mobile ou dans un bundle JavaScript doit être révoquée immédiatement depuis le tableau de bord.

3.2 Générer un token d'accès

Toutes les requêtes sont authentifiées par un token à durée de vie courte. Générez-le avec un POST sur /v1/token.

curl -X POST https://api.blinkid.africa/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "prt_4Tn9Xp",
    "api_key": "sk_live_9f2c8b1a7d4e"
  }'

Réponse :

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-07-25T14:15:00Z"
}

Le token retourné est un JWT signé.

3.3 Utiliser le token

Ajoutez ces deux en-têtes à chaque appel de vérification :

3.4 Expiration

Un token expire 15 minutes après son émission.

Nous recommandons de générer un token par requête de vérification plutôt que de le réutiliser. Cela évite les échecs imprévus lorsqu'un token expire pendant le traitement.

4. Modèle de vérification

Tous les services suivent le même modèle asynchrone.

Étape 1 — Envoyer la requête

Appelez le point de terminaison du service avec les données de l'utilisateur et votre callback_url.

Étape 2 — Recevoir l'accusé de réception

Blink ID répond immédiatement 202 Accepted avec un job_id et un user_id :

{
  "job_id": "job_8Kd2mQ",
  "user_id": "usr_4Tn9Xp",
  "status": "accepted"
}

Cette réponse n'est pas le résultat de la vérification. Elle confirme seulement que la demande est prise en charge.

Étape 3 — Recevoir le résultat

Le résultat final est envoyé à votre callback_url sous forme de webhook :

{
  "job_id": "job_8Kd2mQ",
  "user_id": "usr_4Tn9Xp",
  "status": "approved",
  "message": "Identité vérifiée",
  "reason": "ID_AUTHORITY_MATCH",
  "checks": {
    "id_authority": "match",
    "liveness": "pass",
    "face_match": "pass"
  },
  "risk_score": 12,
  "completed_at": "2026-07-25T14:03:22Z"
}

4.1 Interpréter le résultat

Chaque résultat porte trois informations complémentaires :

Valeurs de status :

4.2 Sécuriser le webhook

Chaque webhook porte un en-tête BlinkID-Signature, calculé en HMAC-SHA256 sur le corps brut de la requête avec votre clé d'API comme secret.

Vérifiez systématiquement cette signature avant de traiter le contenu. Un point de terminaison qui accepte un webhook non vérifié accepte les webhooks de n'importe qui.

import crypto from 'node:crypto';

function verifierSignature(corpsBrut, signatureRecue, apiKey) {
  const attendue = crypto
    .createHmac('sha256', apiKey)
    .update(corpsBrut)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(attendue),
    Buffer.from(signatureRecue),
  );
}

Répondez 200 dès réception. Si votre serveur ne répond pas, nous réessayons avec un délai croissant pendant 24 heures.

5. Services

5.1 Onboarding biométrique

Vérifie l'identité et confirme que la personne est réellement présente. Le service associe un contrôle d'identité — auprès d'une autorité ou sur un document — à un selfie avec détection de vivacité.

Chaque vérification de ce type enrôle également le visage de l'utilisateur, ce qui permet de le re-vérifier plus tard via l'authentification biométrique.

POST /v1/onboarding/biometric

curl -X POST https://api.blinkid.africa/v1/onboarding/biometric \
  -H "BlinkID-Partner-ID: $PARTNER_ID" \
  -H "BlinkID-Token: $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "GN",
    "id_type": "PASSPORT",
    "id_number": "R0123456",
    "selfie": "data:image/jpeg;base64,...",
    "callback_url": "https://votre-app.com/webhooks/blinkid"
  }'

5.2 Onboarding sans biométrie

Vérifie une identité à partir de données personnelles ou d'un identifiant seul, sans selfie. Les informations sont validées directement auprès de la source d'autorité compétente.

À utiliser lorsque votre parcours ne peut pas demander de selfie, ou lorsque la réglementation locale ne l'exige pas.

POST /v1/onboarding/basic

curl -X POST https://api.blinkid.africa/v1/onboarding/basic \
  -H "BlinkID-Partner-ID: $PARTNER_ID" \
  -H "BlinkID-Token: $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "GN",
    "id_type": "NATIONAL_ID",
    "id_number": "1234567890",
    "first_name": "Aminata",
    "last_name": "Diallo",
    "date_of_birth": "1994-03-17",
    "phone_number": "+224620000000",
    "callback_url": "https://votre-app.com/webhooks/blinkid"
  }'

Le webhook renvoie, en plus de status, le détail champ par champ :

{
  "job_id": "job_2Lp7Rk",
  "status": "approved",
  "message": "Identité validée auprès de l'autorité",
  "reason": "ID_AUTHORITY_MATCH",
  "field_matches": {
    "first_name": "match",
    "last_name": "match",
    "date_of_birth": "match",
    "phone_number": "no_match"
  }
}

5.3 Authentification biométrique

Re-vérifie un utilisateur déjà enrôlé, en comparant un nouveau selfie à sa référence biométrique.

À appeler aux moments sensibles : connexion, nouvel appareil, restauration de compte, validation d'une opération à risque. C'est ce service qui évite qu'un utilisateur ayant perdu l'accès à son compte doive en ouvrir un second.

POST /v1/authentication/selfie

curl -X POST https://api.blinkid.africa/v1/authentication/selfie \
  -H "BlinkID-Partner-ID: $PARTNER_ID" \
  -H "BlinkID-Token: $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_4Tn9Xp",
    "selfie": "data:image/jpeg;base64,...",
    "callback_url": "https://votre-app.com/webhooks/blinkid"
  }'

Réponse :

{
  "job_id": "job_9Xm4Vd",
  "user_id": "usr_4Tn9Xp",
  "status": "approved",
  "message": "Utilisateur authentifié",
  "reason": "FACE_MATCH",
  "face_match_score": 0.97
}

5.4 Screening

Crible un profil contre les listes de sanctions internationales et locales, les listes de personnes politiquement exposées (PEP) et les médias défavorables.

Deux modes :

• Ponctuel — un contrôle unique, à l'entrée en relation.
• Continu — le profil reste surveillé. Toute apparition ultérieure sur une liste déclenche un webhook, sans nouvel appel de votre part.

POST /v1/screening

curl -X POST https://api.blinkid.africa/v1/screening \
  -H "BlinkID-Partner-ID: $PARTNER_ID" \
  -H "BlinkID-Token: $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Aminata",
    "last_name": "Diallo",
    "date_of_birth": "1994-03-17",
    "country": "GN",
    "monitoring": "continuous",
    "callback_url": "https://votre-app.com/webhooks/blinkid"
  }'

Réponse :

{
  "job_id": "job_6Qz1Nb",
  "status": "approved",
  "message": "Aucune correspondance",
  "reason": "NO_MATCH",
  "matches": [],
  "monitoring": "continuous"
}

En cas de correspondance :

{
  "status": "pending_review",
  "message": "Correspondance possible sur liste PEP",
  "reason": "PEP_MATCH",
  "matches": [
    {
      "list": "PEP",
      "score": 0.88,
      "matched_name": "Aminata Diallo",
      "source": "Liste nationale des personnes politiquement exposées"
    }
  ]
}

Une correspondance n'est pas une décision. Elle appelle une revue par votre équipe conformité.

6. SDK

Les SDK gèrent la capture guidée du document et du selfie, la détection de vivacité et le pré-traitement de l'image sur l'appareil. Ils sont conçus pour les appareils d'entrée de gamme et les connexions lentes.

Le SDK ne manipule jamais votre clé d'API : votre serveur génère un token, votre application le transmet au SDK.

6.1 Web

npm install @blinkid/web-sdk

import { BlinkID } from '@blinkid/web-sdk';

const blinkid = new BlinkID({
  partnerId: 'prt_4Tn9Xp',
  token: tokenRecupereDepuisVotreServeur,
  environment: 'sandbox', // ou 'production'
});

const resultat = await blinkid.captureOnboarding({
  country: 'GN',
  idType: 'PASSPORT',
  locale: 'fr',
});

// resultat.jobId permet de rapprocher le webhook reçu côté serveur.

6.2 Android

implementation 'africa.blinkid:blinkid-android:1.0.0'

val blinkid = BlinkID.Builder(context)
    .partnerId("prt_4Tn9Xp")
    .token(tokenRecupereDepuisVotreServeur)
    .environment(Environment.SANDBOX)
    .build()

blinkid.startOnboarding(
    country = "GN",
    idType = IdType.PASSPORT,
) { resultat ->
    // resultat.jobId
}

6.3 iOS

pod 'BlinkID', '~> 1.0'

let blinkid = BlinkID(
    partnerId: "prt_4Tn9Xp",
    token: tokenRecupereDepuisVotreServeur,
    environment: .sandbox
)

blinkid.startOnboarding(country: "GN", idType: .passport) { resultat in
    // resultat.jobId
}

7. Couverture

Marchés

Documents pris en charge

8. Erreurs

Les erreurs de requête sont renvoyées en synchrone, avec un code HTTP et un corps structuré :

{
  "error": "invalid_token",
  "message": "Le token a expiré.",
  "status": 401
}

Un échec de vérification n'est pas une erreur d'API : il arrive avec un code 200 puis un webhook portant status: "rejected".

9. Limites de débit

Les réponses portent les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.

10. Passer en production

1. Vérifiez la signature de vos webhooks.
2. Traitez les quatre valeurs de status, y compris pending_review et expired.
3. Générez un token par requête plutôt que de le réutiliser.
4. Confirmez que votre clé de production n'est présente que côté serveur.
5. Testez un rejet et une image illisible, pas seulement le cas nominal.

11. Support

Écrivez à contact@techboxafrica.com en précisant votre partner_id et le job_id concerné. Ces deux éléments permettent de retrouver une vérification immédiatement.