Naar hoofdinhoud springen
ShieldID

Quickstart

De quickstart voor identiteitsverificatie.

Van sandbox-sleutel tot eerste ondertekende webhook, stap voor stap. Elke stap heeft een werkend voorbeeld — kopieer het, vul uw eigen sleutel en URL's in en voer het uit.

Vraag een sandbox-sleutel aanVolledige API-referentie

Stap voor stap

Zeven stappen, één middag.

  1. Een sandbox-sleutel verkrijgen

    Sandbox-sleutels (prefix vk_sand_) worden op aanvraag verstrekt zolang zelfbediening-aanmelding nog wordt gebouwd. Vraag er een aan via het contactformulier — de meeste aanvragen worden dezelfde werkdag afgehandeld. Sandbox-sessies worden nooit gefactureerd, dus er is geen reden om met beginnen te wachten.

  2. Maak uw eerste sessie aan

    Eén aanroep. Stuur een return_url (waar de aanvrager terechtkomt als hij klaar is) en een webhook_url (waar het ondertekende resultaat naartoe gaat). U krijgt een session_id en een verification_url terug.

    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. Geef de aanvrager de link

    Open verification_url en u ziet de gehoste pagina. In een desktopbrowser toont deze een QR-code. Door die te scannen wordt exact dezelfde link doorgegeven aan een telefoon, waar de eigenlijke documentfoto, de liveness-controle en de selfie plaatsvinden. Probeer het nu op uw eigen telefoon.

  4. Zet een webhook-endpoint op

    Laat webhook_url verwijzen naar een route die een POST accepteert, de ruwe request body leest (u hebt die onverwerkt nodig om de handtekening te controleren) en een 2xx-status retourneert. Bij alles wat daarvan afwijkt, probeert ShieldID de aflevering tot drie keer opnieuw.

    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. Controleer de handtekening

    Handel een webhook-body pas af nadat u hebt gecontroleerd dat deze echt van ShieldID afkomstig is. Bereken een HMAC-SHA256 over de ruwe body met uw webhook-secret en vergelijk die met de header 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. Lees het resultaat

    De webhook-payload bevat al alles wat u nodig hebt. Als u het resultaat liever zelf ophaalt, bijvoorbeeld na een redirect, roept u het result-endpoint rechtstreeks aan.

    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. Omgaan met FAILED en een nieuwe poging

    Een sessie die op FAILED uitkomt, bevat een failure_reason. Toon de aanvrager iets bruikbaars. Binnenkort beschikbaar: een FAILED-sessie opnieuw proberen om deze terug te zetten naar PENDING. Behandel FAILED op dit moment als eindstatus en maak een nieuwe sessie aan als de aanvrager het opnieuw wil proberen.

Voordat u de knop omzet

Ga naar productie.

De structuur van het verzoek verandert niet tussen sandbox en productie, alleen de sleutel. Controleer dit voordat u een echte aanvrager door een vk_live_-sessie laat gaan.

  • Vervang vk_sand_ door een vk_live_-sleutel. Verder verandert er niets aan het verzoek.
  • Laat webhook_url verwijzen naar een echt, altijd beschikbaar endpoint dat de handtekening controleert, geen request-bin of laptop.
  • Handel in uw app alle drie de eindstatussen af: VERIFIED, FAILED en EXPIRED, niet alleen het gunstige scenario.
  • Controleer of uw return_url de queryparameters session_id en status leest die ShieldID bij de redirect toevoegt.
  • Raadpleeg de actuele prijzen via GET /v1/pricing/{country} of de prijzenpagina, zodat de kosten in productie u niet verrassen.
  • Houd sandbox-sleutels weg van alles wat een echte aanvrager kan bereiken: een sandbox-sessie is gratis omdat ze niet echt is.

Vragen

Veelgestelde vragen over de quickstart.

Aan de slag

Voer nu de eerste stap uit.

Vraag een sandbox-sleutel aan, plak het eerste cURL-commando in een terminal, en u loopt al voor op de meeste integraties.

Vraag een sandbox-sleutel aanVolledige API-referentie