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_orbs_dev_credential reaches the Active gate with that key in Development, and apk_live_orbs_production_credential reaches the one in Production. When that environment has no Active gate with the key,create-verification-linkreturns a400“not defined or not active” error, and the widget firesbotshield:failurewith reasongate_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.
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.
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.
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 thesite-keyandscopefor 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
tokenandrequest_idfrombotshield:successto your server. botshield:failureleads somewhere useful, including a named refusal such aspass_limit_reached.botshield:cancelleaves the user able to try again, and the built-in action button is either used or hidden withcheckout="false".platform-user-refis 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 checkorganization_id), rejectreplayedtokens and reusedrequest_idvalues, and confirm the gate when you run more than one. - For an Age Gate, you check
age_verdictorage_overwith>=, and fail closed. - With the TypeScript SDK,
serverURLis set andapiKeyAuthincludes theBearerprefix.
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_atyourself. 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.
