Skip to main content
BotShield Gate has two environments that run side by side on the same API. Build and test in Development, then repeat the setup in Production when you are ready to launch. A verification always involves a real person and a real phone, so testing means running the flow yourself.

​
Development and Production

Rules to remember:
  • A gate’s environment is fixed when you place it. A gate placed in Development never becomes a Production gate. Place a second gate in Production. You can reuse the same key in both environments so only your credentials change. The two gates are independent, each with its own gate type, verification mode and logs.
  • Credentials select the environment. BotShield resolves a gate in the environment of the key that calls it. A pk_test_ or bs_dev_ credential reaches the Active gate with that key in Development, and a pk_live_ or bs_production_ credential reaches the one in Production. When that environment has no Active gate with the key, create-verification-link returns a 400 “not defined or not active” error, and the widget fires botshield:failure with reason gate_not_found.
  • The toggle filters the Console. The Development | Production toggle in the page header decides which gates you see and where a new gate is placed.
  • The base URL is the same for both: https://api.botshield.ai/operations, and the same script, https://cdn.botshield.ai/sdk.js.
Keep the credentials in configuration so the switch is one change:

​
The Console Sandbox

Open BotShield Gate → Sandbox. The Sandbox runs the real <botshield-verify> widget against your own keys and gates, so what you see there is what your page will get.
1

Pick a site key

Choose one of your site keys, or paste one. The panel lists the key’s allowed origins. The key’s environment decides which gates you can test.
2

Pick a gate

Select Choose active gate and pick a gate, or type its key. Only Active gates are listed. An Age Gate shows an Age N+ pill.
3

Optional: set a Partner User Ref

Enter a test value to exercise Recent Presence and push. Keep the same value across clicks: the first click runs the live check, and later clicks on a Recent Presence gate can pass instantly. The Link on Verify switch maps to the link-on-verify attribute.
4

Choose Desktop or Mobile

Under Verify link target, Desktop shows the QR modal on the page. Mobile shows the QR code on a computer and opens the app directly when you run the Sandbox on a phone.
5

Click the widget in Live Preview

Scan the QR code with your phone and confirm in the BotShield app.
What the Sandbox shows you: If a test stops with a “pending verification” conflict, select Revoke Pending & Retry.
The Sandbox runs on https://console.botshield.ai. If your site key has allowed origins, add that origin to the key while you test, or the widget fails with origin_not_allowed.

​
Test on a phone

You need a BotShield ID, set up once. 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. The same BotShield ID works for Development and Production gates.
  • Desktop flow. Open your page on a computer, click the widget and scan the QR code with the phone’s camera. Confirm in the app. The modal closes and your page gets botshield:success.
  • Mobile flow. Open your page on the phone itself. The widget opens the app directly; confirm, then switch back to the browser tab. The widget finishes within a few seconds of your return.
  • Reaching a local page from the phone. A phone cannot load your computer’s localhost. Serve your test page over HTTPS on a hostname the phone can reach, and add that origin to your test site key.
Then check the server side: send the token to your backend and confirm your server checks pass. Find the request in the gate’s Verification Logs by its request ID.

​
Exercise every path

Every Unavailable path should leave your user with something to do: a retry, or your fallback. See Result states.

​
Pre-launch checklist

1

Production setup

  • Business verified and a plan active in the Console.
  • A Console passkey added under Settings → Profile → Passkeys.
  • A Production gate placed and Activated, with the key your code uses. Keys are case-sensitive.
  • A pk_live_ site key whose Allowed Origins list every production origin, and nothing else. A live key needs at least one origin.
  • A bs_production_ API key stored as a server secret, if you call the API.
2

On the page

  • Every <botshield-verify> has the site-key and scope for Production. scan-mode="modal" is the default flow, whether or not the attribute is present.
  • The script loads from https://cdn.botshield.ai/sdk.js, and your Content Security Policy allows it.
  • Your code handles both botshield:success shapes, including token: null.
  • botshield:failure leads somewhere useful, botshield:cancel leaves the user able to try again, and the built-in action button is either used or hidden with checkout="false".
  • platform-user-ref is an opaque ID, not an email address.
3

On the server

  • Every protected action checks the result server-side. Nothing is trusted from the browser alone.
  • You check organization_id, reject reused request_id values, and confirm the gate when you run more than one.
  • You accept completed or pass, and read the status right away for fast-path results.
  • For an Age Gate, you check age_verdict or age_over with >=, and fail closed.
  • With the TypeScript SDK, serverURL is set and apiKeyAuth includes the Bearer prefix.
4

Webhooks and timeouts

  • Your endpoint is added under Settings → Developer Tools → Webhooks and verifies signatures. It branches on the payload’s top-level environment, because one endpoint receives both environments.
  • You time requests out at expires_at yourself. No webhook arrives for a request the user never opened, or for a fast-path pass.
5

One real run

Run one Production verification end to end from a real phone, and find it in the gate’s Verification Logs.

​
Next steps

Place a gate

Place and activate the Production gate.

Keys and environments

Manage site keys and API keys.

Rate limits

Limits per key type.

Webhooks

Receive results on your server.