Keys and environments

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, 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. 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, 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.

​

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.

​

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.
• 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.

​

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

​

Passkey confirmation

The Console asks you to confirm with your console passkey when you do any of these in Production:

• Place a gate
• Activate a gate
• Register an agent
• Rotate an agent’s key

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. Activating a Production gate checks all three requirements, in this order: verified business, active plan, passkey. If one is missing, the Console tells you which and the gate stays a Draft.

​

Team access

Invite teammates under Settings → Team. Every Console member is an admin today: invitations are sent with the admin role, and admins can do everything on this page. There are no limited or read-only roles yet, so invite only people who should be able to create and revoke keys. Each admin confirms Production actions with their own console 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