link setting decides whether a pass also links the person to your account for them, making it a Secured Account. It is part of the gate’s policy document.
Set it
- Console
- Gates API
When you place a gate, choose under Who may pass › Link their account when they pass: required, when you send your user ref (
optional) or never. A preset pre-fills it: Presale and Promo pre-fill required, the other presets and BotShield Gate (Custom) pre-fill when you send your user ref.To change it later, open the gate and change the same row in its Configuration card, then select Save. On a Production gate, confirm with your Developer passkey.An Age Gate has no link row: it never links.link reads as never. A gate placed before release 3.4, whose document has no link, follows its older secure-accounts switch: on reads as optional, off reads as never. An organization-wide document can tighten every gate: required is tighter than optional, which is tighter than never.
What the person sees
The person is told before a pass links them. When a pass will link them and their BotShield ID is not yet linked to your account, the card in the BotShield app says the pass links them with your company, before they confirm. A person who is already linked is not told again. The link happens in the same passkey confirmation as the pass. There is no second tap and no separate step. When the confirmation completes, the pass and the link are recorded together. What you learn is the same as for any Secured Account: the token carriestrusted: true with trusted_since and last_pass_at, and never the person’s identity. See Token and webhooks.
Send your user ref
Your user ref is your own stable identifier for the signed-in user, such as your internal user ID. BotShield stores it only as a one-way hash. Use an opaque ID, never an email address.- Widget
- Server
Set
platform-user-ref on the element:required needs a user ref
On a link: required gate, a request without a user ref is refused before anything is shown to the person:
botshield:failure, with code and message in detail:
reason is mobile_create_failed on a phone. Widget versions before 3.0.15 report only reason. See Widget versions.
If the setting changes to required while a request is open, BotShield checks again when the person confirms. A pass that did not run the linking confirmation is then refused: the request ends failed and gate.unavailable carries failure_code: "link_requires_user_ref".
On a required gate the page cannot opt out: notarize="false" has no effect. On an optional gate, notarize="false" keeps that placement’s passes anonymous. See Secured Accounts widget.
An Age Gate never links
An Age Gate always reads aslink: never, whatever its document or the organization’s says. The age answer is read on the person’s phone and is never tied to an account. This is a platform rule, not a setting.
Choose a setting
Next steps
Gates API
Place a gate with its policy document.
Secured Accounts
What a link gives you, and what it never does.