メインコンテンツへスキップ
ShieldID

クイックスタート

本人確認クイックスタート。

sandbox キーから最初の署名付き Webhook まで、順番に進めます。各ステップには動作する例があります。コピーして、ご自身のキーと URL に置き換えて実行してください。

sandbox キーをリクエストAPI リファレンス全文

ステップごとの手順

7つのステップ、1日で完了。

  1. sandbox キーを取得する

    Sandbox キー（プレフィックス vk_sand_）は、セルフサービス登録を準備中のため、リクエストに応じて発行しています。お問い合わせフォームからご依頼ください。ほとんどのリクエストは営業日の当日中に対応しています。Sandbox のセッションは課金されないため、すぐに開始していただけます。

  2. 最初のセッションを作成する

    呼び出しは1回だけです。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 エンドポイントを用意する

    webhook_url を、POST を受け付け、生のリクエストボディを読み取り(署名の確認には未解析のボディが必要です)、2xx ステータスを返すルートに指定してください。それ以外の場合、ShieldID は配信を最大3回再試行します。

    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. 署名を検証する

    webhook のボディが確かに ShieldID から送られたものだと確認できるまで、その内容に基づく処理は行わないでください。webhook シークレットを使って生のボディに対する 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. 結果を確認

    webhook のペイロードには、必要な情報がすべて含まれています。リダイレクト後など、結果をご自身で取得したい場合は、結果エンドポイントを直接呼び出してください。

    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 は、署名を検証する、常時稼働の実際のエンドポイントに指定してください。リクエストビンやノートパソコンは使用しないでください。
  • アプリで3つの終了状態、VERIFIED、FAILED、EXPIRED のすべてに対応してください。正常に完了するケースだけでは不十分です。
  • return_url が、リダイレクト時に ShieldID が付加する session_id と status のクエリパラメータを読み取れることを確認してください。
  • GET /v1/pricing/{country} または料金ページで最新の料金を確認し、本番環境での請求に驚くことがないようにしてください。
  • sandbox キーは、実際の申請者がアクセスできる場所には置かないでください。sandbox のセッションが無料なのは、実際の認証ではないためです。

ご質問

クイックスタートのFAQ。

はじめる

さっそく最初のステップを実行しましょう。

sandbox キーをリクエストし、最初の cURL コマンドをターミナルに貼り付ければ、ほとんどの連携よりもすでに一歩先に進んでいます。

sandbox キーをリクエストAPI リファレンス全文