Skip to main content
This guide takes you from a new Console account to a verified human on your own page. You create a site key and a development gate, add the <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 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:
An invalid or expired token is a normal result, not an error:
Allow the action only when all of these hold:
  • valid is true and claims.verified is true.
  • The token is for your organization: you sent audience, or claims.organization_id is yours. Copy your Organization ID from Settings → Developer Tools → API Keys in the Console. POST /sdk/create-session also returns it as organization.id.
  • The token has not been used before. A token is good for one check: verify-token refuses a second check of the same token with valid: false and replayed: true. Record each request_id you accept and reject repeats as well, because a local JWKS check cannot see replays.
The SDK returns the same fields in camelCase (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 or GET /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.