Passer au contenu principal
ShieldID

Guide de démarrage

Le guide de démarrage de la vérification d'identité.

De la clé de bac à sable au premier webhook signé, dans l'ordre. Chaque étape comprend un exemple fonctionnel — copiez-le, remplacez par votre propre clé et vos propres URL, puis exécutez-le.

Demander une clé de bac à sableRéférence complète de l'API

Étape par étape

Sept étapes, un après-midi.

  1. Obtenir une clé de bac à sable

    Les clés de bac à sable (préfixe vk_sand_) sont émises sur demande pendant que l'inscription en libre-service est en cours de développement. Faites votre demande par le formulaire de contact — la plupart des demandes sont traitées le jour ouvrable même. Les sessions en bac à sable ne sont jamais facturées; il n'y a donc aucune raison d'attendre pour commencer.

  2. Créer votre première session

    Un seul appel. Envoyez un return_url (là où le demandeur arrive lorsqu'il a terminé) et un webhook_url (là où le résultat signé est envoyé). Vous recevez en retour un session_id et un verification_url.

    bash
    curl -X POST https://api.shieldid.ca/v1/sessions \
  -H "X-Api-Key: vk_sand_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.example/verified",
    "webhook_url": "https://yourapp.example/hooks/shieldid",
    "expected_name": "Jordan Smith",
    "locale": "en",
    "metadata": { "application_id": "app_9182" }
  }'

  3. Remettez le lien au demandeur

    Ouvrez verification_url et vous verrez la page hébergée. Dans un navigateur de bureau, elle affiche un code QR : en le numérisant, vous transmettez exactement le même lien à un téléphone, où se déroulent la photo du document, le défi de preuve de vie et l'égoportrait. Essayez-le dès maintenant sur votre propre téléphone.

  4. Mettez en place un point de terminaison webhook

    Dirigez webhook_url vers une route qui accepte une requête POST, lit le corps brut de la requête (vous en avez besoin non analysé pour vérifier la signature) et renvoie un code d'état 2xx. Dans tout autre cas, ShieldID réessaie la livraison jusqu'à trois fois.

    javascript
    import express from "express";
const app = express();

app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  // Verify the signature before you trust this body — see the next step.
  console.log("Received a webhook:", req.body.toString());
  res.status(200).send("ok");
});

app.listen(3000);

  5. Vérifiez la signature

    N'agissez pas sur le corps d'un webhook avant d'avoir vérifié qu'il provient bien de ShieldID. Calculez un HMAC-SHA256 sur le corps brut avec votre secret de webhook et comparez-le à l'en-tête X-Bio-Signature.

    javascript
    import crypto from "node:crypto";

function isValidShieldIdSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader || "";
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(provided, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody must be the exact, unparsed request body
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  const ok = isValidShieldIdSignature(req.body, req.headers["x-bio-signature"], process.env.SHIELDID_WEBHOOK_SECRET);
  if (!ok) return res.status(401).send("invalid signature");

  const result = JSON.parse(req.body);
  // result.session_id, result.status, result.checks, …
  res.status(200).send("ok");
});

  6. Lisez le résultat

    La charge utile du webhook contient déjà tout ce dont vous avez besoin. Si vous préférez récupérer le résultat vous-même — après une redirection, par exemple — appelez directement le point de terminaison de résultat.

    bash
    curl https://api.shieldid.ca/v1/sessions/ses_9f2c1a/result \
  -H "X-Api-Key: vk_sand_your_key"

# → { "session_id": "ses_9f2c1a", "status": "VERIFIED", "checks": { "document": "PASS", … }, … }

  7. Gérez FAILED et une nouvelle tentative

    Une session qui atteint l'état FAILED comporte un failure_reason. Montrez quelque chose d'utile au demandeur. Bientôt : relancer une session FAILED pour la remettre à PENDING. Pour l'instant, considérez FAILED comme un état final et créez une nouvelle session si le demandeur souhaite réessayer.

Avant de basculer

Passez en production.

La structure de la requête ne change jamais entre le bac à sable et la production — seule la clé change. Confirmez ces points avant de faire passer un vrai demandeur par une session vk_live_.

  • Remplacez vk_sand_ par une clé vk_live_. Rien d'autre ne change dans la requête.
  • Dirigez webhook_url vers un point de terminaison réel, toujours actif, qui vérifie la signature — pas un request-bin ni un portable.
  • Gérez les trois états finaux dans votre application : VERIFIED, FAILED et EXPIRED, et pas seulement le scénario idéal.
  • Confirmez que votre return_url lit les paramètres de requête session_id et status que ShieldID ajoute lors de la redirection.
  • Consultez les tarifs actuels avec GET /v1/pricing/{country} ou la page des tarifs, afin que les frais de production n'aient rien de surprenant.
  • Gardez les clés du bac à sable hors de portée de tout ce qu'un vrai demandeur pourrait atteindre — une session en bac à sable est gratuite parce qu'elle n'est pas réelle.

Questions

FAQ du démarrage rapide.

Commencer

Exécutez la première étape dès maintenant.

Demandez une clé de bac à sable, collez la première commande cURL dans un terminal, et vous aurez déjà de l'avance sur la plupart des intégrations.

Demander une clé de bac à sableRéférence complète de l'API