본문으로 건너뛰기
ShieldID

퀵스타트

신원 인증 퀵스타트입니다.

sandbox 키 발급부터 첫 서명된 웹훅까지 순서대로 안내합니다. 각 단계에는 실제로 동작하는 예제가 있으니, 복사해서 고객님의 키와 URL로 바꾼 뒤 실행해 보세요.

sandbox 키 요청전체 API 레퍼런스

단계별 안내

일곱 단계, 한나절이면 충분합니다.

  1. sandbox 키 받기

    Sandbox 키(접두사 vk_sand_)는 셀프 서비스 가입이 준비되는 동안 요청 시 발급됩니다. 문의 양식을 통해 요청해 주세요. 대부분의 요청은 영업일 기준 당일 처리됩니다. Sandbox 세션에는 요금이 청구되지 않으므로 바로 시작하셔도 됩니다.

  2. 첫 번째 세션 만들기

    호출 한 번이면 됩니다. return_url(신청자가 완료 후 도착하는 곳)과 webhook_url(서명된 결과가 전송되는 곳)을 보내 주세요. 응답으로 session_id와 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. 신청자에게 링크 전달하기

    verification_url을 열면 호스팅 페이지가 표시됩니다. 데스크톱 브라우저에서는 QR 코드가 나타나며, 이를 스캔하면 동일한 링크가 휴대폰으로 전달됩니다. 실제 신분증 촬영, 라이브니스 확인, 셀카 촬영은 휴대폰에서 이루어집니다. 지금 바로 본인 휴대폰으로 직접 해 보세요.

  4. 웹훅 엔드포인트 준비하기

    webhook_url이 POST 요청을 받고, 원본 요청 본문을 읽고(서명을 확인하려면 파싱되지 않은 상태여야 합니다), 2xx 상태 코드를 반환하는 경로를 가리키도록 설정하세요. 그렇지 않으면 ShieldID가 전송을 최대 세 번까지 다시 시도합니다.

    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. 서명 확인하기

    웹훅 본문이 실제로 ShieldID에서 온 것인지 확인하기 전에는 그에 따라 처리하지 마세요. 웹훅 시크릿으로 원본 본문에 대한 HMAC-SHA256을 계산하고 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. 결과 확인하기

    웹훅 페이로드에는 이미 필요한 정보가 모두 들어 있습니다. 리디렉션 이후처럼 결과를 직접 가져오고 싶다면 결과 엔드포인트를 직접 호출하세요.

    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. FAILED 처리와 재시도

    FAILED 상태가 된 세션에는 failure_reason이 포함됩니다. 신청자에게 도움이 되는 안내를 보여 주세요. 곧 제공 예정: FAILED 세션을 재시도하여 PENDING으로 되돌리는 기능. 현재는 FAILED를 최종 상태로 간주하고, 신청자가 다시 시도하려면 새 세션을 만들어 주세요.

전환하기 전에

프로덕션으로 전환하세요.

요청 형식은 sandbox와 프로덕션 간에 달라지지 않으며, 키만 다릅니다. 실제 신청자를 vk_live_ 세션으로 진행하기 전에 다음 사항을 확인하세요.

  • vk_sand_ 키를 vk_live_ 키로 교체하세요. 요청의 다른 부분은 바뀌지 않습니다.
  • webhook_url이 서명을 확인하는, 항상 가동 중인 실제 엔드포인트를 가리키도록 설정하세요. 리퀘스트 빈이나 노트북은 안 됩니다.
  • 앱에서 세 가지 최종 상태인 VERIFIED, FAILED, EXPIRED를 모두 처리하세요. 정상 흐름만 다루면 안 됩니다.
  • return_url이 리디렉션 시 ShieldID가 덧붙이는 session_id 및 status 쿼리 매개변수를 읽는지 확인하세요.
  • GET /v1/pricing/{country} 또는 요금 페이지에서 현재 요금을 확인하여 프로덕션 청구 금액에 놀라지 않도록 하세요.
  • 실제 신청자가 접근할 수 있는 곳에는 sandbox 키를 두지 마세요. sandbox 세션은 실제가 아니기 때문에 무료입니다.

문의

퀵스타트 FAQ.

시작하기

지금 바로 첫 단계를 실행해 보세요.

sandbox 키를 요청하고 첫 번째 cURL 명령을 터미널에 붙여넣으면, 이미 대부분의 연동보다 앞서 가고 계신 겁니다.

sandbox 키 요청전체 API 레퍼런스