Skip to main content
This guide sets up BotShield for personal agents in your Development environment, then moves it to Production:
  • The account holder’s approval of exact terms, through the botshield.ai/approval extension (steps 1 to 7).
  • The BotShield Signal API at every order: verified, true or false (step 8).
  • Optional: a passkey check in a signed-out session, through botshield.ai/human-presence (at the end).
Every BotShield call is made by your server with your secret key. For what each piece does, see Personal agents (Poppy).

What you need first

  • A working Poppy core. Your poppy.json, verification of the signed Poppy-Session on each request, and Poppy’s OAuth sign-in, so you know which of your accounts a request is for. See the Personal Agent Protocol. @botshield/poppy covers only BotShield’s part, after those checks.
  • Node.js 20 or later, or Cloudflare Workers.
  • @botshield/poppy 0.2.0 or later, from npm. 0.2.0 adds confirmLink and runs on Cloudflare Workers; 0.1.0 does neither. The source is in Bot-Shield/poppy-extensions.
  • A BotShield Console account at console.botshield.ai.

1. Create a Development key

1

Open your API keys

In the Console, select Development in the header, then go to Settings → Developer Tools → API Keys. Create a key if you have none. It starts bs_dev_.
2

Give it Gates API access

On the key’s row, check Gates API access. Approvals are sent with the Gates API, and you place Actions and gates with it below. See Gates API.
3

Turn on A link waits for my server's confirm

On the same row, turn on A link waits for my server’s confirm. A link made with this key is then not live at the tap: it goes live when your server confirms which account it is for (step 6). BotShield refuses a confirm for a different account than the one the link was started for.
Keep the key on your server, for example as BOTSHIELD_SECRET_KEY. Never send it to an agent or a browser.

2. Register a Trusted Agent

The approval card in the BotShield app is headed by the agent your request is sent under. Register one for your company:
  1. Go to Agents Ask → Agent registry and select Register Agent, in Development.
  2. Agent name: letters and digits only, for example PersonalAgents. You pass this name to AccountHolderApproval as agent.
  3. Display name: what the person reads on the card, for example Personal agents.
  4. Allowed action categories: any. Actions requests don’t use them.
The Console shows an agent key once. You don’t need it for these extensions: every call uses your secret key. See Register an agent. You need one BotShield Action for each kind of action that asks for approval, and one gate that makes your customers’ accounts BotShield Verified. Place them with your Development key. You can also place them in the Console.
1

The Action

POST /gates-api/actions/create. The actKey is what you pass to AccountHolderApproval as actionKey.
See Place an action with the API.
2

The link gate

POST /gates-api/create. A gate that makes the account BotShield Verified on the tap, open to anyone:
You use it once per customer, in step 6. See The link setting.
Check data.error on every answer. The environment comes from the key: a bs_dev_ key places Development Actions and gates.

4. Publish poppy.json

List the extension under extensions in your /.well-known/poppy.json. Version 1 has no other fields.
If you add the optional passkey check (at the end), list botshield.ai/human-presence too. In a scope description, you can tell the person that the account holder approves each change in the BotShield app.

5. Add the server code

Create the API client and one handler per Action, once, at startup.

An action that needs the account holder’s approval

Call approvals.require() on every request for the action, after your Poppy Session and access token checks. It starts the request for approval the first time, answers with its state on each repeat, and checks BotShield’s signed answer once the account holder approves. perform() runs your action at most once.
  • meaning decides whether a repeat is the same request. A request that asks for anything else starts a new request for approval, with a new approval_id.
  • terms: 1 to 12 rows, each label up to 40 characters and each value up to 80. Every term that affects the action must be a row, including any total. The person reads them on their phone.
  • summary is plain language, no links. Its first 90 characters, without formatting, head the card.
  • Options: ttlSeconds (how long the person has to answer, 60–86400, default 600), retryAfter (default 5 seconds), checkEvery (BotShield is asked at most once per this many seconds per request, however often the agent repeats; default 10).
  • A rate limit or an outage at BotShield leaves the request waiting. isTransient() tells you when a thrown error decided nothing.

MCP tools

On an MCP server, return approvalToolResult() instead. It is an error result (isError: true) with text any MCP client can act on, and the object in structuredContent. Read the id back from the call’s _meta:
An MCP client that does not know the extensions will not send _meta. Giving the tool an optional approval_id argument, and adding the id to the result’s text, lets any model repeat the call with it. Without the id, require() still finds the request by what it means, within the same account and client.

More than one server

The default store keeps state in memory, which suits one process. With more than one server or instance, pass a store that implements the Store interface on shared storage (Redis, Postgres, a Durable Object). Its swap must be atomic per id: that is what keeps an action to at most once.

6. Get each customer BotShield Verified once

The account holder can be asked only once their account is BotShield Verified. Get each customer BotShield Verified once, from a signed-in page of yours, with the link gate from step 3:
confirmLink collects the finished token and checks it once with the account your session shows, which confirms the link that waits for your server. Send the same partnerUserRef you pass to approvals.require() as account. A customer who is not BotShield Verified gets NotLinkedError from approvals.require(), and nothing reaches anyone.

7. Test it

With your Development key, against https://api.botshield.ai, and the BotShield app on your own phone:
  • GET /.well-known/poppy.json lists botshield.ai/approval.
  • Get a test account BotShield Verified (step 6). confirmLink answers live.
  • Ask for the action. Your server answers 403 with account_holder_approval_required, state: "requested" and Retry-After. A card arrives in the BotShield app, headed by your agent’s display name, with your summary and terms.
  • Repeat with BotShield-Approval-Id before you answer: the same object, still requested.
  • Approve with your passkey, then repeat: the action is performed. BotShield is asked at most once per checkEvery (10 seconds by default), so a repeat right after you approve can still read requested.
  • Repeat again: the first result comes back, and the action is not performed again.
  • Ask again and decline in the app: state: "declined", nothing done. Let one expire: state: "expired".
  • Ask for the action with an account that is not BotShield Verified: NotLinkedError, no card sent.
  • Call the action as an MCP tool from an ordinary MCP client: the tool error text tells the model what to do, and the repeated call succeeds.
The live demo runs this flow, and its source is in demo/couchtour.

8. Check every order with the BotShield Signal API

When a customer’s own agent places orders on their account, check each one. The first time, the account holder approves the agent once, with their passkey. After that, your server asks at every order and gets verified: true or false, and nobody waits. The account holder can remove the agent in the BotShield app, and the next check answers false. It uses the same key, the same BotShield Verified customers and the same botshield.ai/approval extension. See BotShield Signal API for the calls.

9. Go to production

  1. A Production key. Create a bs_production_ key, check Gates API access (you confirm with your Developer passkey), and turn on A link waits for my server’s confirm.
  2. A Production Trusted Agent. Register it under Production. Agents do not move between environments.
  3. Production Action and link gate. Place them again with the Production key. A Production gate activates only when your business is verified, you have a verified domain, and your plan has room. See Go to production.
  4. Shared storage. Pass a store on shared storage if you run more than one instance.
  5. Get your customers BotShield Verified with the Production key and the Production link gate (step 6).
  6. Swap the key on your server and publish poppy.json on your production domain.

Optional: a passkey check in a signed-out session

For an action in a session with no signed-in account, the account holder’s approval doesn’t apply: there is no BotShield Verified account to ask. botshield.ai/human-presence asks for a passkey confirmation on a phone instead, under a rule you set at one of your gates. For example: one free trial per verified phone number. For a signed-in account, use the approval above.
1

Place the gate

POST /gates-api/create. No BotShield Verified step, no sign-up list, and one pass per verified phone number, ever:
The key is what you pass to HumanPresence as gate. See The policy document and Who may pass.
2

Declare it

Add "botshield.ai/human-presence": [{ "version": "1" }] under extensions in your poppy.json.
3

Check it on the request

Call presence.require() with the verified Poppy Session. A pass belongs to that Session (client_id, sid and User ID) for passFor seconds (default 3600), and is good for this gate only.
While the check waits, the presence object carries verification_uri, a link on app.botshield.ai. The agent shows the link, or a QR code of it, and must not open it itself. If the gate’s rule refuses it, for example because this verified phone number already started a trial, the state is refused and nothing is done. On an MCP server, return presenceToolResult(p.presence) and read the id from _meta[PRESENCE_ID_META].
4

Test it

Start a trial: your server answers 403 with human_presence_required and a verification_uri. Open the link on your phone, confirm, repeat: the trial starts. Start another from a new Session with the same phone: state: "refused".

Next steps

Personal agents (Poppy)

What the extensions do, and what each side learns.

Gates API

Place and run gates from your server.

BotShield Actions

Actions and the act string.

@botshield/poppy on npm

The package and its versions.