Skip to main content
From BotShield 4.0, a link can wait for your server. The person taps Get BotShield Verified and confirms with their passkey in BotShield, and the link is then pending. It goes live only when your server tells BotShield which account it is for, with your secret API key, and BotShield finds that it is the same account the link was started for. This closes a gap a page cannot close by itself. The browser names the account in 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.
A link that is not confirmed within 24 hours of the tap expires. Nothing becomes BotShield Verified, and the person can start again from your page.

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.
Your /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 as data.error with HTTP 200, like every BotShield operation. Nothing becomes BotShield Verified on any error.
link_account_mismatch means the person who tapped was looking at a different account from the one your session shows. Do not retry with the account from the link. Send only what your own session says.

Confirm in the token check instead

If you already send every token to POST /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. 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.