14-3 通行証を本社で確かめる（siteverify）
入口の係が「大丈夫」と判断すると、お客さんに小さな通行証を渡します。お客さんは申込書とその通行証を事務所へ出します。
ここで通行証を見るだけなら、よく似たものを自分で作った相手を止められません。本物かは、発行元の本社に聞くしかありません。
いま読んでいるこのサイト（Cloudflare Lab）でも、書き込みを受けるのは Worker です。本社に問い合わせる手順を、その中に書くことになります。
Learning goals
この節でできるようになること
- token の有効期間と回数を言える
- Siteverify API へ何を送るかを言える
- success と error-codes の読み方を言える
- 確かめないと何が起きるかを言える
1. 通行証は 1 回きり
Section titled “1. 通行証は 1 回きり”入口でもらう通行証は、一度使ったらそれきりです。長く使える通行証は、写しを作られると危険です。
Cloudflare では、この通行証を token と呼びます。公式は、token の長さが最大 2,048 文字、有効期間が発行から 300 秒（5 分）で、1 回しか検証できないと明記しています。
使い回した token は、公式の言うとおり timeout-or-duplicate という error code で拒否されます。5 分を過ぎた場合も同じ code です。
通行証には砂時計が付いていて、5 分で砂が落ち切ります。
つまり、通行証は 5 分で切れ、使えるのは 1 回だけです。
2. 本社に問い合わせる
Section titled “2. 本社に問い合わせる”事務所が本社へ聞くときは、通行証と一緒に合鍵も送ります。合鍵は、その事務所が本物だという証しです。
Cloudflare では、問い合わせ先が Siteverify API です。公式は、https://challenges.cloudflare.com/turnstile/v0/siteverify へ POST で送ると示しています。必須の項目は 2 つで、secret（widget の secret key）と response（widget が作った token）です。
任意の項目は remoteip（訪問者の IP アドレス）と idempotency_key（再送を安全にする UUID）です。送り方は form でも JSON でもよく、返事はいつも JSON です。
次の命令は「合鍵と通行証を本社へ送る」ものです。読めなくても大丈夫です。
const body = new FormData();body.append("secret", SECRET_KEY);body.append("response", token);
const res = await fetch( "https://challenges.cloudflare.com/turnstile/v0/siteverify", { method: "POST", body },);const result = await res.json();実行すると、本物かどうかを書いた JSON が返ります。
合鍵と通行証をそろえて本社へ送り、返事を待ちます。
つまり、確認は「secret と response を Siteverify API へ送る」だけです。
3. 返事の読み方
Section titled “3. 返事の読み方”本社からの返事は、まず可否が 1 行あり、駄目なときは理由が付きます。
公式は、返事の項目として success（成功したか）、challenge_ts（解かれた時刻）、hostname（出された店名）、error-codes（失敗の理由）などを挙げています。まず読むのは success です。
error-codes の意味も表にあります。invalid-input-response は token が不正か期限切れ、timeout-or-duplicate は同じ token の二度目です。
返事の紙は、上に可否、下に理由の欄があります。
つまり、success で通し、error-codes で原因をたどります。
4. 確かめないと意味がない
Section titled “4. 確かめないと意味がない”通行証を見た「ふり」で通していると、係を置いた意味がなくなります。それは外から分かりません。
公式は、サーバー側での検証が必須だと書いています。理由は 3 つで、token は偽造できる、期限切れになる、1 回しか使えない、です。
公式は、Siteverify API を呼ぶのは backend だけにするよう求めています。secret key を画面側に出すと、確認そのものを迂回されます。
通行証を見ずに通している事務所の横を、機械がそのまま通り抜けています。
つまり、Siteverify API を呼ばない限り、係を置いても守れていません。
Cloudflare Lab での使われ方
Section titled “Cloudflare Lab での使われ方”ここで紹介した確認が、いま読んでいる Cloudflare Lab でどう使われるかを見ます。
Cloudflare Lab の書き込みの入口は Worker になる予定です。届いた token を Worker の中で Siteverify API へ送り、success が真のときだけ受け付けます。実測は後で追記します。
つまずきやすいところ
Section titled “つまずきやすいところ”この節のまとめ
Section titled “この節のまとめ”- token は最大 2,048 文字、300 秒（5 分）有効の 1 回きりです。
- 確認は secret と response を Siteverify API へ送るだけです。
- 返事は success で判断し、駄目なときは error-codes を読みます。
この節で出てきた言葉を、つながりの順に並べると次のようになります。
図のラベル: 係が渡す通行証 token（5 分・1 回） / サーバー側に届く / 合鍵を添えて送る secret と response / 本社の窓口 Siteverify API / 可否を読む success / 駄目な理由を読む error-codes / 二度使うと失敗 timeout-or-duplicate
次の節では、この係を店のどこに置くかを考えます。
この節のチェック
© 2026 osdse