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 human confirming on 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, Who may pass levers 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 a gate and pick a gate, or type its key. The panel shows the gate’s Who may pass line. A Draft or Archived gate is marked as paused and answers with gate_not_active.
3

Optional: set a Partner User Ref

Enter a test value, such as an opaque user ID. It maps to the platform-user-ref attribute. Keep the same value across runs to watch a pass limit refuse you by name.
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 with your passkey. The modal closes and your page gets botshield:success.
  • Mobile flow. Open your page on the phone itself. The widget hands off to the BotShield app (on iPhone Safari, tap Open BotShield); 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

  • All four Go to production steps done: a verified domain, business verification, a Developer passkey, and a plan with room for your production gates.
  • 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. Each origin sits under a verified domain.
  • Who may pass set the way you want it on the Production gate.
  • 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 sends token and request_id from botshield:success to your server.
  • botshield:failure leads somewhere useful, including a named refusal such as pass_limit_reached. 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 pass audience (or check organization_id), reject replayed tokens and reused request_id values, and confirm the gate when you run more than one.
  • 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.
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.