Development and Production
Every gate, agent, and key belongs to one of two environments.
The Console dashboard calls Development your sandbox. Until production is on, the dashboard’s key card shows your sandbox gate, and you can try a verification there before you write any code.
Both environments use the same API base URL,
https://api.botshield.ai/operations, and the same widget script. The key you send selects the environment, and a key works only with gates and agents from its own environment.
A gate is looked up in the environment of the key that calls it. Test and development keys (pk_test_…, bs_dev_…) reach Development gates. Live and production keys (pk_live_…, bs_production_…) reach Production gates. The same gate key (scope) can exist in both environments. The two are separate gates, each with its own gate type, verification mode, and status, and a key only ever reaches the one in its own environment. When that environment has no Active gate with the gate key, the call fails: the widget reports botshield:failure with reason gate_not_found (or gate_not_active when the gate exists but is a Draft or Archived), and POST /sdk/create-verification-link answers statusCode 400 with “not defined or not active”.
The environment toggle
The Development | Production toggle sits in the page header of the BotShield Gate and Agents Ask pages. It controls which gates and agents you see, and the environment of anything you create from that page. Your choice carries across pages and is remembered in your browser. It starts on Production. Two areas are not filtered by the toggle. Settings → Developer Tools lists the keys for both environments together, each with an environment badge. Analytics covers all environments.Verified domains
A verified domain proves the site is yours. Production needs one: a live site key’s allowed origins must sit on a verified domain, and a production gate cannot be activated until your organization has at least one. Development never waits on a domain, and test keys are exempt.1
Add the domain
Go to Settings → Developer Tools → Verified Domains, enter the root domain your company owns, for example
meridianairlines.example, and select Add domain. The Verify your domain step on the dashboard’s Go to production card does the same thing.2
Add the TXT record
The Console shows a TXT record Name and Value. Add that record at your DNS provider.
3
Verify
Select Verify (on the dashboard, Check now). BotShield looks the record up. A new record can take a few minutes to show up, so try again if the first check fails.
meridianairlines.example lets a live key use https://meridianairlines.example, https://www.meridianairlines.example, and https://*.meridianairlines.example. Gates that are already live keep running; the domain is checked when you activate a gate or save a live key’s origins, not on each request.
Site keys
A site key is the public credential the BotShield widget uses in the browser. It goes in your HTML as thesite-key attribute, so anyone can read it. What protects it is the list of allowed origins: BotShield accepts a request with a site key only when the browser’s Origin matches that list.
1
Open Site Keys
Go to Settings → Developer Tools → Site Keys and select New Site Key.
2
Name it and pick the environment
Enter a name, for example “Meridian checkout”, and choose
test or live. Names must be unique within an environment.3
Add allowed origins
Add every origin that will load the widget, then create the key. An origin is scheme plus host, with a port if you use one, and no path:
https://www.meridianairlines.example. For a live key, every origin must sit on a verified domain.4
Copy the public key
The key appears in the list as
pk_test_… or pk_live_… and stays visible there, so you can come back for it.Allowed origins
- Matching ignores case and a trailing slash.
testkeys also accepthttp://localhostandhttp://127.0.0.1on any port, so local development works without an entry.livekeys accept only the origins you list, and must have at least one. The Console refuses to create alivekey with an empty list, and refuses an edit that would remove its last origin.- Every origin on a
livekey must be a verified domain or one of its subdomains. The Console refuses an origin outside your verified domains and names that origin in its message. testkeys may have an empty list. Atestkey with no origins is accepted from any origin, so give it origins too once it is used anywhere other than your own machine.- A request with no
OriginorRefererheader is rejected when the key has origins, so a site key does not work from a server or from curl unless you send anOriginheader.
Edit origins or revoke
Use the pencil icon on a key to add or remove origins, then Save origins. Changes apply to new requests. Alive key keeps at least one origin, so add the new origin before you remove the old one. Use the trash icon to revoke a key. Revoking a live key asks for your Developer passkey. A revoked site key stops working at once, and the widget on any page that still uses it fails. There is no rotate action for site keys. To replace one, create a new key, deploy it, then revoke the old key.
API keys
An API key is the secret credential your server uses to call the API. It is never checked against an origin, so anyone who holds it can call the API as you.1
Open API Keys
Go to Settings → Developer Tools → API Keys.
2
Create a key for one environment
Select New Development Key or New Production Key. You can hold several keys per environment, for example one per service.
3
Copy it now
The full key (
bs_dev_… or bs_production_…) is shown once, in the green panel. Copy it into your secret manager. After you leave the page, the Console shows only a masked version.Organization ID
The API Keys tab also shows your Organization ID (org_…) with a Copy button. It is the value BotShield writes into the organization_id claim of every attestation token, and the organization_id that GET /verification/status returns. Store it next to your API key, send it as audience when you call POST /sdk/verify-token, and compare it on your server before you trust a token or a status. See Verify on your server. The same value comes back from POST /sdk/create-session as organization.id. One Organization ID covers both environments.
Agent keys
An agent key (bs_agent_<Name>__<secret>) is the secret credential for one Agents Ask agent in one environment. You receive it once, when you register the agent under Agents Ask → Trusted Agents → Register Agent.
See Register an agent for the full walkthrough.
Which key goes where
Send API keys, grant tokens, and agent keys as
Authorization: Bearer <credential>.
Production requirements
Development is open from the moment you sign up. Production asks for three things, and the dashboard’s Go to production card walks you through them in order: domain, business, Developer passkey, then plan.1
Verify your domain
Add one TXT record to prove the site is yours. See Verified domains.
2
Submit your business for review
Enter your legal name, EIN, website, and intended use. BotShield runs automatic checks first. If they do not all pass, the submission shows in review and a person looks, usually within a day. A reviewer may ask for one more document. Development keeps working meanwhile.
3
Create your Developer passkey
Under Settings → Profile → Passkeys, select Add passkey. This passkey belongs to your Console login and is separate from the one in your BotShield app. Removing it does not affect your BotShield app.
Activating a production gate
Activating a Production gate checks, in this order:- Your business is verified.
- Your organization has at least one verified domain.
- Your plan allows another production gate.
- You confirmed with your Developer passkey in the last five minutes.
Passkey confirmation
The Console asks you to confirm with your Developer passkey when you do any of these in Production:- Place a gate, or activate one
- Change a gate’s type or age threshold
- Turn Notarize account with BotShield on or off for a gate
- Change a gate’s Who may pass rules
- Rotate or revoke an API key
- Revoke a
livesite key - Register an agent, or rotate or revoke an agent’s key
- Revoke a Verified Account
Team access
Invite teammates under Settings → Team. Invitations from the Console are sent with the Admin role. A Console member has one of two roles:
Invite only people who should be able to create and revoke keys as Admins. Each admin confirms Production actions with their own Developer passkey. A passkey is personal and is not shared across the team.
Analytics
The Analytics page reports on both products across all environments.
Verifications your server creates with an API key count in the same places as verifications the widget starts: the gate’s Overview metrics and the Analytics page.
Open a gate from the BotShield Gate page for its own Overview, Verification Logs (Request ID, Status, Duration, Created), and Activity Logs. The log view exports to CSV. Use the Request ID to match a row to the
request_id in your own records. Logs contain no personal data about the human.
Handle keys safely
- Keep API keys and agent keys in a secret manager or environment variables. Never commit them, and never send them to the browser or a mobile app.
- Use Development keys on laptops and in CI. Give Production keys only to production services.
- Create one API key per service, so you can revoke one without touching the rest.
- Rotate or revoke a key as soon as someone who had it leaves, or when it may have appeared in a log, a ticket, or a chat.
- Do not log
Authorizationheaders. If you turn on the SDK’s debug logger, keep it out of production. - Treat a site key as public, and keep its allowed origins tight. Prefer exact origins to wildcards.
- Check Last used on the API Keys tab from time to time and revoke keys nobody uses.
Next steps
Place a gate
Create a gate and get its key for the
scope attribute.Register an agent
Get an agent key for Agents Ask.
Webhooks overview
Add an endpoint and copy its signing secret.
API overview
Use your keys against the API.
