<botshield-verify> widget, handle its success event, and confirm the result on your server. Development is not billed.
Before you start
- A BotShield Console account. Sign up at console.botshield.ai.
- A BotShield ID, so you can complete a verification yourself. The quickest way is app.botshield.ai (public beta): create a passkey and confirm in the browser, no download. The BotShield app for iPhone and Android is optional and in review. See Testing.
- A page you can edit and a server endpoint you can add.
The flow
Every gate asks. Each pass is a new passkey confirmation on the person’s phone, so every success carries a signed token.Build it
1
Create a site key
In the Console, set the environment toggle in the page header to Development. Open Settings → Developer Tools → Site Keys and select New Site Key.Copy the public key. A development site key starts with
pk_test_. Add your site’s origin (for example https://shop.example.com) to the key’s allowed origins. localhost is always allowed for pk_test_ keys. A pk_live_ key must list at least one origin, and each one must sit under a verified domain.A site key is public. It is safe in your page source because it only works from its allowed origins.2
Place and activate a gate
Open Verified Accounts in the sidebar, then the BotShield Gates tab, and select Place a gate. Give it a name, check the key derived from it, and choose the Human Gate type.The gate’s key is the value you put in the widget’s
scope attribute. It is case-sensitive.Placing a gate creates a Draft. A draft does not answer verifications. Open the gate and select Activate. Leave Who may pass at its default for now: anyone, as often as they like. See Place a gate for the full lifecycle and Who may pass for the levers.3
Add the widget to your page
Load the script once, then place the element where the user takes the action. This example uses the mock brand Meridian Airlines and a gate with the key (
checkout.scan-mode="modal" names the widget’s flow, and it is the default. On desktop the widget shows a QR code for the user to scan with their phone. On a phone it hands off to the BotShield app. The embed snippet in the Console includes the attribute.scope is the embed attribute for the gate key.) See Web component for every attribute, event, and method.4
Handle botshield:success
The widget dispatches
botshield:success on the element when the human is verified. The event bubbles, so you can also listen on a parent.event.detail carries token (a signed JWT), request_id, and via: "ceremony". See Web component for the other fields.On botshield:failure, offer the user another way forward. Do not treat it as proof of a bot. When a gate’s Who may pass levers refuse someone, the failure carries the reason by name, such as pass_limit_reached. See Result states.5
Verify on your server
Never trust the browser event on its own. Send the token to (An invalid or expired token is a normal result, not an error:Allow the action only when all of these hold:
POST /sdk/verify-token. Pass your Organization ID as audience, and BotShield rejects a token that was issued for any other organization. If you call with your secret API key as Authorization: Bearer bs_… instead, BotShield uses your key’s organization as the audience.census is the SDK’s name for BotShield Gate.) The example uses botshield-sdk 2.2.1, the current release. Install it with npm add botshield-sdk. A valid token returns:validistrueandclaims.verifiedistrue.- The token is for your organization: you sent
audience, orclaims.organization_idis yours. Copy your Organization ID from Settings → Developer Tools → API Keys in the Console.POST /sdk/create-sessionalso returns it asorganization.id. - The token has not been used before. A token is good for one check:
verify-tokenrefuses a second check of the same token withvalid: falseandreplayed: true. Record eachrequest_idyou accept and reject repeats as well, because a local JWKS check cannot see replays.
requestId, organizationId) and does not unwrap the envelope. Read result.data.data and check result.data.error first.Server-to-server instead
You can run the whole flow from your server with an API key: create a grant token, create a verification link, send the user to it, and read the result from a webhook orGET /verification/status. Use this when you cannot embed the widget, for example in a native app or an email link. See Verify on your server.
Next steps
Web component
Every attribute, event, and method on
<botshield-verify>.Verify on your server
Token verification, local JWKS verification, and the server-to-server flow.
Webhooks
Receive
gate.human_verified and gate.unavailable on your endpoint.Go to production
Verified domain, business verification, Developer passkey, and a plan.
