Démarrage rapide

AYIiD permet à un vérificateur (banque, opérateur mobile money, place de marché) de demander une preuve d’identité à un détenteur, sans jamais manipuler ses données personnelles. Le sujet est désigné par un identifiant décentralisé pseudonyme (did:ayi) ; le détenteur autorise chaque partage par signature. Ce guide utilise le SDK @ayiid/sdk, mais tout est faisable en HTTP brut.

1. Installer le SDK

Le SDK est isomorphe (Node 18+ ou navigateur) et n’a aucune dépendance runtime.

1npm install @ayiid/sdk

2. Initialiser le client

Le client échange votre clé API contre un jeton d’accès de courte durée (mis en cache et renouvelé automatiquement sur expiration).

1import { AyiidClient } from '@ayiid/sdk';
2
3const ayiid = new AyiidClient({
4  apiKey: process.env.AYIID_API_KEY,      // secret, cote serveur
5  baseUrl: 'https://api.ayiid.example',   // origine de l'API
6  webBaseUrl: 'https://app.ayiid.example' // origine web (URL de consentement)
7});

3. Créer une demande de vérification

Indiquez le sujet (subjectRef, un DID), les attributs demandés (scope) et un motif lisible (reason) présenté au détenteur. Par défaut, le mode est PROOF_ONLY : un simple booléen signé, sans aucune donnée.

1const demande = await ayiid.createVerification({
2  subjectRef: 'did:ayi:z6Mkf...abcd',
3  scope: ['identity', 'is_adult'],
4  reason: 'Ouverture de compte : verification d age',
5  mode: 'PROOF_ONLY',
6  callbackUrl: 'https://exemple.com/webhooks/ayiid',
7  requireLiveness: { minLevel: 'L2', maxAgeDays: 30 }
8});
9
10// { requestId: 'req_...', status: 'PENDING' }
11const url = ayiid.hostedVerifyUrl(demande.requestId);

4. Faire consentir le détenteur

Présentez l’URL hébergée de consentement (hostedVerifyUrl) au détenteur, par exemple sous forme de lien ou de QR code. Il y voit qui demande quoi et pourquoi, puis approuve ou refuse dans son application AYIiD en signant sa décision (EIP-712).

5. Recevoir le résultat

Deux options, combinables : interroger le statut de la demande, ou recevoir un webhook signé sur votre callbackUrl.

Par scrutation

1const etat = await ayiid.getVerification(demande.requestId);
2// { requestId: 'req_...', status: 'APPROVED' | 'REJECTED' | 'PENDING' | ... }

Par webhook signé

À l’issue de la demande, le moteur appelle votre callbackUrl avec un corps signé en HMAC-SHA256. Vérifiez toujours la signature sur le corps brut.

1import { verifyWebhookSignature, SIGNATURE_HEADER } from '@ayiid/sdk';
2
3app.post('/webhooks/ayiid', async (req, res) => {
4  const brut = req.rawBody; // corps brut, avant parsing JSON
5  const signature = req.headers[SIGNATURE_HEADER];
6  if (!verifyWebhookSignature(process.env.AYIID_WEBHOOK_SECRET, brut, signature)) {
7    return res.status(401).end();
8  }
9  const evenement = JSON.parse(brut);
10  // traiter l'attestation...
11  res.status(200).end();
12});