Skip to main content
The BotShield Console is where you create the credentials your integration uses and where you move from testing to live traffic. This guide covers the two environments, verified domains, the three kinds of key, which key belongs in which part of your system, and what the Console asks for before it lets you work in Production.

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.
A gate’s environment is fixed when you place it, and an agent’s when you register it. You cannot move one between environments. Place the gate again in Production when you are ready, using the same key (scope) if you want your markup to stay the same.
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.
A verified root covers itself and every subdomain: verifying 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 the site-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.
  • test keys also accept http://localhost and http://127.0.0.1 on any port, so local development works without an entry.
  • live keys accept only the origins you list, and must have at least one. The Console refuses to create a live key with an empty list, and refuses an edit that would remove its last origin.
  • Every origin on a live key 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.
  • test keys may have an empty list. A test key 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 Origin or Referer header is rejected when the key has origins, so a site key does not work from a server or from curl unless you send an Origin header.
An origin list is what stops someone who copies your site key from using it on their own site. Keep the list on a live key tight, and prefer exact origins to wildcards.

Edit origins or revoke

Use the pencil icon on a key to add or remove origins, then Save origins. Changes apply to new requests. A live 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.
When you create or rotate a development key, the Console reminds you that it is rate limited: 10 requests a minute, 100 an hour, and 300 a day, one at a time. Development keys are for building and testing, never for production traffic. Each key in the list shows its environment, a masked value, when it was created, and when it was last used.

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.
You do not have to pick a plan to go live. Every organization starts on Free, and Free covers your first production gate. Choose a plan under Settings → Plans when you need more production gates. One plan covers every product.

Activating a production gate

Activating a Production gate checks, in this order:
  1. Your business is verified.
  2. Your organization has at least one verified domain.
  3. Your plan allows another production gate.
  4. You confirmed with your Developer passkey in the last five minutes.
If one is missing, the Console says which and the gate stays a Draft. The domain is checked before the passkey prompt, so you are never asked for a passkey only to be refused. Gates that are already live are not affected when you change domains or plans later.

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 live site key
  • Register an agent, or rotate or revoke an agent’s key
  • Revoke a Verified Account
Deleting the organization also asks for it. A confirmation is good for five minutes. After that, the next Production action asks again. If you remove your last passkey, these actions lock until you add one. Development actions never ask.

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 Authorization headers. 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.