platform-user-ref, and anything in the browser can be changed. Your server knows which account is signed in. The confirm lets your server check the link before it counts.
Which keys wait
A link started on your page always waits. Get BotShield Verified runs with your site key, and its link waits for your server’s confirm on every key, including keys created before 4.0. A site key alone never makes an account BotShield Verified. A request your server starts follows its secret API key’s setting, a link waits for my server’s confirm:
Change the setting for an API key in the BotShield Console under Settings, Developer Tools. Only an organization admin can change it, and for a Production key the Console asks for your Developer passkey first. Links that were live before you turned the setting on stay live.
The flow
1
The person taps and confirms
Your page shows Get BotShield Verified with your user ID in
platform-user-ref. The person confirms with their passkey in BotShield. BotShield tells them it is finishing with your company.2
BotShield tells you a link is waiting
Your page receives
botshield:success with the request_id, token: null and trusted: false. Your webhook endpoint receives account.link_pending with the same request_id. Nothing is BotShield Verified yet. No handle is sent, and the account is not in your registry as BotShield Verified.3
Your server confirms
Your page sends the
request_id to your own server, inside the person’s signed-in session. Your server calls POST /sdk/confirm-link with its secret API key, the request_id, and the user ID that session shows.4
The link goes live
When the account matches, the link is live. The response carries the account’s
handle and the finished token, and your endpoint receives account.link_live and account.secured. The widget on your page shows BotShield Verified within a few seconds.Where the confirm runs
Run the confirm in a request that carries the person’s signed-in session on your side, so the account you send is the one your session shows, not one the browser named./api/botshield/confirm handler reads the user from its own session and calls POST /sdk/confirm-link. It never takes the account from the request body.
Use account.link_pending to know that a link is waiting, for example to confirm it when the person next signs in, before expires_at. The webhook carries no account, so it cannot tell you which user to send by itself.
POST /sdk/confirm-link
Call it from your server only, with Authorization: Bearer <secret API key>. A site key (pk_…) or an agent key is refused with secret_key_required.
The confirm is safe to repeat. Confirming a live link again with the same account answers
linked: true with first_time: false and a new token, and sends no second webhook.
The SDK method is census.confirmLink in botshield-sdk 4.0.1 and later.
Errors
Errors arrive asdata.error with HTTP 200, like every BotShield operation. Nothing becomes BotShield Verified on any error.
Confirm in the token check instead
If you already send every token toPOST /sdk/verify-token, you can confirm there. With your secret API key, add partner_user_ref to the check. When the token’s link is pending, the check confirms it and answers with a link object:
A token for a link that is not pending carries no
link object.
What reads as BotShield Verified while a link waits
A pending link counts for nothing until your server confirms it.
A pending link never blocks the account’s real owner. If someone else’s link for the account is waiting, the owner can still verify it.
Try it in Development
In the Console, open Verified Accounts, then Try it, and verify your own account with your Development key. The link reads Waiting until it is confirmed. In Development, Confirm as my server stands in for your server and runs the same confirm. In Production, only your server can confirm.Next steps
Token and webhooks
account.link_pending, account.link_live and the token claims.Account lifecycle
Pending, live, paused and ended.
