Quick start

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

Build it

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.A site key is public. It is safe in your page source because it only works from its allowed origins.

Place and activate a gate

Open BotShield Gate and select Place a gate. Give it a name and a key, choose the Human gate type, and choose a verification mode:

Recent Presence: returning humans pass instantly.
Live: every verification asks for a new biometric confirmation.

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. See Place a gate for the full lifecycle.

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.

<script src="https://cdn.botshield.ai/sdk.js"></script>

<form id="booking-form" action="/bookings" method="post">
  <botshield-verify
    site-key="pk_test_…"
    scope="checkout"
    scan-mode="modal"
  ></botshield-verify>

  <button id="book-button" type="submit" disabled>Book flight</button>
</form>

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 opens the BotShield app directly. 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.

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.

<script>
  const widget = document.querySelector("botshield-verify");

  widget.addEventListener("botshield:success", async (event) => {
    const { token, request_id } = event.detail;

    const response = await fetch("/api/botshield/confirm", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ token, request_id }),
    });

    if (response.ok) {
      document.getElementById("book-button").disabled = false;
    }
  });

  widget.addEventListener("botshield:failure", (event) => {
    console.log("BotShield unavailable:", event.detail.reason);
  });
</script>

event.detail has two shapes you must handle:

Case	`token`	`via`	`request_id`
The human completed a confirmation on their phone	A signed JWT	`"ceremony"`	Present
A recognized returning human passed a Recent Presence gate instantly	`null`	`"precheck"`	Present

On botshield:failure, offer the user another way forward. Do not treat it as proof of a bot. See Result states.

Verify on your server

Never trust the browser event on its own. When you have a token, send it to POST /sdk/verify-token. The endpoint needs no API key, because the signed token is the proof.

curl -X POST https://api.botshield.ai/operations/sdk/verify-token \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJhbGciOiJFUzI1NiIs…"}'

import { BotShield } from "botshield-sdk";

// serverURL is required. The package does not default to production.
const botShield = new BotShield({
  serverURL: "https://api.botshield.ai/operations",
});

export async function verifyAttestation(token: string) {
  const result = await botShield.census.verifyToken({}, { token });

  if (result.data.error) {
    throw new Error(result.data.error.message);
  }

  const check = result.data.data;
  const ok =
    check?.valid === true &&
    check.claims?.verified === true &&
    check.claims.organizationId === process.env.BOTSHIELD_ORG_ID;

  return ok ? check.claims!.requestId : null;
}

(census is the API’s name for BotShield Gate.) A valid token returns:

{
  "data": {
    "data": {
      "valid": true,
      "claims": {
        "request_id": "req_3f9a1c…",
        "verified": true,
        "organization_id": "org_…",
        "timestamp": "2026-09-21T17:04:11.000Z",
        "nonce": "req_3f9a1c…_1790010251000",
        "issued_at": 1790010251,
        "expires_at": 1790010371
      }
    }
  }
}

An invalid or expired token is a normal result, not an error:

{ "data": { "data": { "valid": false, "reason": "Invalid token — signature verification failed" } } }

Allow the action only when all of these hold:

valid is true and claims.verified is true.
claims.organization_id is your organization. Copy your Organization ID from Settings → Developer Tools → API Keys in the Console. POST /sdk/create-session also returns it as organization.id.
You have not already accepted this request_id. The token lives 120 seconds and verify-token does not consume it, so record each request_id and reject repeats.

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.

Handle the Recent Presence case

An instant pass happens only on a Recent Presence gate, and only when you identify the user to the widget with the platform-user-ref attribute and BotShield recognizes them from an earlier verification on your site. See BotShield ID. The sample above does not set platform-user-ref, so it always returns a token.When token is null, there is nothing to pass to verify-token. Look the request_id up from your server instead.

curl "https://api.botshield.ai/operations/verification/status?request_id=req_3f9a1c…"

export async function confirmInstantPass(requestId: string) {
  const result = await botShield.verification.getStatus({}, { requestId });

  if (result.data.error) {
    throw new Error(result.data.error.message);
  }

  const record = result.data;
  const verified = record.status === "completed" || record.status === "pass";

  return (
    record.found === true &&
    verified &&
    record.organizationId === process.env.BOTSHIELD_ORG_ID &&
    record.scope === "checkout"
  );
}

verification/status returns its payload directly under data, not under data.data.

An instant pass is recorded with status: "pass", not "completed". Accept either value as Verified, and never test for "completed" alone. The instant-pass record reads "expired" 60 seconds after the check, so look it up as soon as your page reports success. If it is already "expired", ask the user to verify again. No webhook is sent for an instant pass.

If you want a signed token on every verification, set the gate’s verification mode to Live. Live gates always ask for a new confirmation and always return a token.

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.

Keys and environments

Site keys, API keys, and moving from Development to Production.

Get Started

BotShield Gate

Trusted Accounts

Agents Ask

Webhooks

Console

Server SDK

Integrations

Concepts

Changelog

Before you start

The flow

Build it

Server-to-server instead

Next steps

Web component

Verify on your server

Webhooks

Keys and environments

​Before you start

​The flow

​Build it

​Server-to-server instead

​Next steps

Web component

Verify on your server

Webhooks

Keys and environments

Before you start

The flow

Build it

Server-to-server instead

Next steps