Skip to main content
A human sets up the BotShield app once, on their own phone, and secures it with a passkey. That is their BotShield ID: a standing proof-of-human that belongs to them. The same BotShield ID works at every partner. You do not issue it, store it, or see it. You see results.

​
What it changes for your users

The first time a person meets a BotShield gate, they create a passkey — at app.botshield.ai (public beta, no download) or in the BotShield app — and confirm with their device biometric. After that, they already have a BotShield ID, and every later gate is quicker, on your site and on any other platform’s.

​
Verification modes

You choose a verification mode when you place a gate. It decides how much a BotShield ID can do on its own. An Age Gate always uses Live. It always asks for a new confirmation. BotShield decides whether a human’s presence is recent enough. The rule is not exposed and you do not configure it. If you need a guarantee that a human confirmed at this moment, use Live. On a Recent Presence gate, an instant pass reaches your page as botshield:success with token: null and via: "precheck". The result state is Verified either way. To confirm an instant pass on your server, call GET /verification/status with the request_id straight away. It reports status: "pass" rather than "completed", and the record reads "expired" 60 seconds after the check. If it has already expired, ask the user to verify again. The Quick start has the code.

​
Recognizing a returning user

BotShield does not know that the visitor on your page is someone it has seen before unless you say which of your users they are. You do that with a reference of your own.
Set platform-user-ref to your own stable ID for the signed-in user.
link-on-verify defaults to true. Set link-on-verify="false" to verify without linking.
Here is what happens with that reference:
1

First verification

The human confirms on their phone. Because linking is on, BotShield remembers that this reference, at your organization, belongs to that BotShield ID.
2

Later verifications

You send the same reference. BotShield recognizes it and sends a push to the human’s phone. The widget’s modal reads “Check your phone” and still shows the QR code as a fallback. On a Recent Presence gate, a human whose presence is recent skips the prompt entirely.
Without a reference, every visitor is new to BotShield. They always get the QR code or deep link, and a Recent Presence gate never passes them instantly.

​
What stays private

  • Your reference is hashed. BotShield stores a hash of platform-user-ref that is specific to your organization, not the raw value. It is never returned to you or shown to anyone else.
  • You never receive a BotShield identifier on the Gate rail. No widget event, token claim, status response, or gate webhook carries one. You correlate results with your own request_id and your own reference.
  • Nothing links your users across partners. Another partner using the same human’s BotShield ID learns nothing about your site, and you learn nothing about theirs.
Use an opaque internal ID as the reference. Do not use an email address, phone number, or name. BotShield does not need it, and an opaque ID keeps personal data out of the request.
Agents Ask identifies a linked human differently, with an opaque ID that is unique to each agent. See The privacy boundary.

Place a gate

Choose the gate type and verification mode.

Web component

platform-user-ref, link-on-verify, and every other attribute.

Result states

Verified and Unavailable, and how to design for both.

The privacy boundary

What crosses to you and what never does.