Hoppa till huvudinnehållet
ShieldID

Snabbstart

Snabbstarten för identitetsverifiering.

Från sandbox-nyckel till första signerade webhook, steg för steg. Varje steg har ett fungerande exempel – kopiera det, byt in din egen nyckel och dina egna URL:er och kör det.

Begär en sandbox-nyckelFullständig API-referens

Steg för steg

Sju steg, en eftermiddag.

  1. Skaffa en sandbox-nyckel

    Sandbox-nycklar (prefix vk_sand_) utfärdas på begäran medan självbetjäningsregistrering byggs. Fråga via kontaktformuläret – de flesta förfrågningar hanteras samma arbetsdag. Sandbox-sessioner faktureras aldrig, så det finns ingen anledning att vänta med att komma igång.

  2. Skapa din första session

    Ett enda anrop. Skicka en return_url (dit den sökande hamnar när verifieringen är klar) och en webhook_url (dit det signerade resultatet skickas). Tillbaka får du ett session_id och en 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. Ge den sökande länken

    Öppna verification_url så visas den hostade sidan. I en webbläsare på dator visas en QR-kod – när den skannas förs exakt samma länk över till en mobil, där själva dokumentfotot, liveness-kontrollen och selfien görs. Testa med din egen mobil direkt.

  4. Sätt upp en webhook-endpoint

    Peka webhook_url mot en route som tar emot POST, läser den råa request-bodyn (den måste vara oparsad för att signaturen ska kunna kontrolleras) och returnerar statuskod 2xx. Annars försöker ShieldID leverera igen upp till tre gånger.

    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. Verifiera signaturen

    Agera inte på en webhook-body förrän det är kontrollerat att den verkligen kommer från ShieldID. Beräkna en HMAC-SHA256 över den råa bodyn med din webhook-hemlighet och jämför med headern 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. Läs resultatet

    Webhook-payloaden innehåller redan allt som behövs. Vill du hellre hämta resultatet själv – till exempel efter en omdirigering – anropa result-endpointen direkt.

    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. Hantera FAILED och nytt försök

    En session som hamnar i FAILED har en failure_reason. Visa något användbart för den sökande. Kommer snart: nytt försök för en FAILED-session, som återställer den till PENDING. Än så länge gäller FAILED som slutgiltigt tillstånd – skapa en ny session om den sökande vill försöka igen.

Innan du slår på strömmen

Gå över till produktion.

Requestens form ändras aldrig mellan sandbox och produktion – bara nyckeln. Bekräfta följande innan en riktig sökande skickas genom en vk_live_-session.

  • Byt ut vk_sand_ mot en vk_live_-nyckel. Inget annat i requesten ändras.
  • Peka webhook_url mot en riktig endpoint som alltid är igång och som verifierar signaturen – inte en request-bin eller en laptop.
  • Hantera alla tre slutgiltiga tillstånd i appen: VERIFIED, FAILED och EXPIRED, inte bara det lyckade flödet.
  • Kontrollera att din return_url läser parametrarna session_id och status som ShieldID lägger till vid omdirigeringen.
  • Kontrollera aktuell prissättning med GET /v1/pricing/{country} eller prissidan, så att kostnaderna i produktion inte kommer som en överraskning.
  • Håll sandbox-nycklar borta från allt som en riktig sökande kan nå – en sandbox-session är gratis eftersom den inte är på riktigt.

Frågor

Vanliga frågor om snabbstarten.

Kom igång

Kör det första steget direkt.

Begär en sandbox-nyckel, klistra in det första cURL-kommandot i en terminal, så ligger du redan före de flesta integrationer.

Begär en sandbox-nyckelFullständig API-referens