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. After that they already have a BotShield ID, and every later gate skips the setup, on your site and on any other platform’s.
Every row ends the same way. A gate always asks: each pass is a new passkey confirmation on the person’s phone. Having a BotShield ID, or having passed a gate a minute ago, never lets a person through without confirming.
What a BotShield ID tells your gate
A gate learns one thing from a BotShield ID beyond “a person confirmed just now”: whether it meets the gate’s Who may pass bar.- Passes per person. BotShield counts passes per person at your gate, not per account. A person with two accounts on your platform has one count.
- Real for at least N days. BotShield counts the distinct days on which the person’s BotShield ID has completed a passkey confirmation, at any gate on any platform. You set the bar; you never receive the number.
pass_limit_reached or real_days_not_met. See Result states.
Telling BotShield which of your users is asking
You do not need to identify your users for a gate to work. When you do, you send a reference of your own, and it enables two things: the person can link their account with you, and once they have, BotShield can send a later request to their phone as a push.- Widget
- Server API
Set
platform-user-ref to your own stable ID for the signed-in user.link-on-verify attribute and link_on_verify field are accepted and have no effect. See Alias window.
What stays private
- Your reference is hashed. BotShield stores a hash of
platform-user-refthat 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_idand your own reference. - Counts stay inside BotShield. The key BotShield uses to count passes per person is private to your platform and never leaves BotShield. The number of real days is never sent.
- Nothing links your users across partners. Another partner whose gate the same person passes learns nothing about your site, and you learn nothing about theirs.
Who may pass
Passes per person, and BotShield ID real for at least N days.
Web component
platform-user-ref 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.
