> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# BotShield Signal API

> For agentic commerce: know the agent placing an order is the one your BotShield Verified customer approved. One call, a fresh answer: verified: true or false.

The BotShield Signal API, for agentic commerce, tells your server whether the agent placing an order is bound to a BotShield Verified customer: its account holder approved it, with a passkey. Your server asks at each order and gets a fresh answer, verified: true or false. After the account holder's one-time approval, nobody is asked at an order. BotShield is not the checkout, the wallet or the card: the wallet pays and your server places the order.

When a customer's assistant buys at your company, you want to know that this is the assistant the account holder said may buy for them. The account holder approves the assistant once per company, in the BotShield app, with their passkey. At every checkout after that, your server asks BotShield: is this the assistant the account holder approved? BotShield answers verified, true or false, fresh, for that order.

It is the `assistant` Action of [`botshield.ai/approval`](https://docs.botshield.ai/poppy/overview): the same extension and the same 403 response to the agent. Only what the account holder approves changes.

Nothing new for your customer: they approve in the BotShield app they already use to be BotShield Verified with you, and their agent needs no BotShield account or credential. Your company connects its own server to BotShield.

## How it works

**1. The first checkout asks the account holder**

The first time an assistant buys for a customer at your company, you ask the account holder to approve it. They get one request in the BotShield app, **Let {assistant} buy for you**, with rows naming the assistant and where it comes from, and approve with their passkey.

`AssistantGate` and the MCP tools read the assistant's name from the `client_name` in its OAuth Client ID Metadata Document, fetched from its `client_id` URL. When BotShield records the approval, it reads that document again, and refuses unless the title the account holder approved is **Let {client_name} buy for you**. If you build the request yourself, use that exact title.

**2. BotShield records the approval**

Once the account holder approves, BotShield reads the assistant's metadata again and records the approval only if the name the person saw is still the assistant's `client_name`. Your server receives **BotShield's pairwise ID** for this approval: one company, one account, one assistant (`client_id`) and, under Poppy, that assistant's user ID for your company (`sub`).

**3. Every checkout is checked**

At each checkout, after you verify the Poppy Session, your server asks BotShield with the account, the pairwise ID or the assistant's `client_id`, the assistant's user ID, and your own reference for the order. BotShield answers verified, true or false (`match` in the response), with a time and a check ID. The person is not asked again.

**4. The person can remove the assistant**

The person sees each approved assistant under your company in the BotShield app and can remove it. Every check after that answers false, and your next checkout asks the account holder again.

## What verified: true means

* **`verified: true` (the `match` field) means the account holder approved this assistant for this account:** its `client_id` and, when you send it, its user ID for your company. It is only as strong as your own verification of the request's Poppy signature. It is not consent to an order's terms. When you want the account holder to approve what is being bought (the items, the total, the address), ask for that action itself with [`botshield.ai/approval`](https://docs.botshield.ai/poppy/setup#5-add-the-server-code).
* **An answer is for one order.** Check every order. Each answer carries its own `checked_at` and `check_id`.
* **False carries no reason.** Whether the assistant was never approved, was removed, or is a different assistant, the answer is the same.
* **The pairwise ID is yours.** Keep it on your server. Never give it to the assistant.
* **BotShield records each check** (your company, the time, the result), never what was bought. Your order reference is recorded hashed.

## Set up

You need the same setup as [`botshield.ai/approval`](https://docs.botshield.ai/poppy/setup), with one Action for the assistant:

1. **A secret key with Gates API access** (`bs_dev_…` to start). See [Setup, step 1](https://docs.botshield.ai/poppy/setup.md#1-create-a-development-key).
2. **A Trusted Agent** whose agent name the request is shown under. Any category: Actions requests don't use it. See [Setup, step 2](https://docs.botshield.ai/poppy/setup.md#2-register-a-trusted-agent).
3. **An Action with the key `assistant`.** Place it in the Console under **Verified Accounts › BotShield Actions**, or with the Gates API:

   ```bash theme={null}
   curl -s https://api.botshield.ai/operations/gates-api/actions/create \
     -H "Authorization: Bearer $BOTSHIELD_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"Let an assistant buy for you","actKey":"assistant"}'
   ```
4. **BotShield Verified customers.** Only the holder of a [Verified Account](https://docs.botshield.ai/verified-accounts/overview.md) can approve an assistant. Get each customer BotShield Verified once, as in [Setup, step 6](https://docs.botshield.ai/poppy/setup.md#6-get-each-customer-botshield-verified-once).

The assistant's metadata must be readable: its `client_id` is an `https://` URL on a DNS name, the document answers 200 without a redirect, its `client_id` field matches, and its `client_name` is 1 to 60 characters. If `AssistantGate` or the MCP tools can't read the name, the account holder is not asked. If BotShield can't read it when recording the approval, `register` answers `not_approved`.

## In Node.js: `AssistantGate`

`AssistantGate` in [`@botshield/poppy`](https://www.npmjs.com/package/@botshield/poppy) does your company's side: it asks the account holder the first time, records the approval, keeps the pairwise ID in its store, and checks at every checkout. It needs `@botshield/poppy` 0.2.x or later. Source: [Bot-Shield/poppy-extensions](https://github.com/Bot-Shield/poppy-extensions).

```typescript theme={null}
import { BotShieldApi, AssistantGate, approvalResponse, isTransient, APPROVAL_ID_HEADER } from "@botshield/poppy";

const api = new BotShieldApi({ secretKey: process.env.BOTSHIELD_SECRET_KEY! }); // bs_…
const assistants = new AssistantGate({ api, agent: "PersonalAgents" });        // your Trusted Agent's name

app.post("/checkout", async (req, res) => {
  // After your Poppy Session and access token checks:
  try {
    const r = await assistants.require({
      account: req.account.id,                                        // your reference for the signed-in account
      assistant: { clientId: req.poppy.clientId, userId: req.poppy.userId }, // from the verified Session
      orderRef: req.body.order_id,                                    // your reference for this order
      approvalId: req.get(APPROVAL_ID_HEADER),                        // BotShield-Approval-Id, on a repeat
    });

    if (r.allowed) {
      // This order's fresh answer: r.checkedAt, r.checkId. Place the order.
      return res.json(await placeOrder(req.account.id, req.body));
    }
    if ("refused" in r) {
      // assistant_unknown: its metadata couldn't be read, so nobody was asked.
      return res.status(403).json({ error: "assistant_unknown" });
    }
    const out = approvalResponse(r.approval); // 403: the account holder is asked "Let {assistant} buy for you"
    return res.status(out.status).set(out.headers).json(out.body);
  } catch (e) {
    if (isTransient(e)) return res.status(503).set("Retry-After", "5").json({ error: "unavailable" });
    throw e;
  }
});
```

* Pass the assistant's `client_id` and `sub` from the verified Poppy Session. Without Poppy, pass the `clientId` you know and no `userId`.
* The agent sees the usual `account_holder_approval_required` response with an approval object, tells the user to approve in the BotShield app, and repeats its request with `BotShield-Approval-Id`. In an MCP tool, return `approvalToolResult(r.approval)` instead.
* After the person removes the assistant, the next check answers false and `require()` asks the account holder again.
* Options: `ttlSeconds` (60–86400, default 600), `retryAfter`, `checkEvery`, and `store`. With more than one server, pass a shared `store`, as for [`AccountHolderApproval`](https://docs.botshield.ai/poppy/setup#more-than-one-server). The store holds the pairwise ID.
* A customer whose account is not BotShield Verified can't be asked: `require()` throws a `BotShieldError` with `code` `not_linked`, and nothing is sent.

## From your own agent: Partner MCP tools

If your company's own agent speaks MCP, it can use three tools on the hosted server at `https://mcp.botshield.ai/mcp`, authenticated with your company's secret key with Gates API access, `Authorization: Bearer bs_…` (not an agent key). See [MCP server](https://docs.botshield.ai/agents-ask/mcp-server.md) for connecting a client.

| Tool | When | Input | Output |
| - | - | - | - |
| `request_assistant_approval` | The first time an assistant buys for a customer. Sends "Let {assistant} buy for you" to the account holder. | `request_id` (a UUID you choose; reuse it to read its status), `partner_user_ref`, `agent` (your Trusted Agent's name), `assistant_client_id`, `assistant_user_id` (optional) | `request_id`, `status` (`queued`), `expires_at`. An error result when the assistant's metadata can't be read. |
| `assistant_approval_status` | Until the request is decided. | `request_id`, `partner_user_ref`, `agent`, `assistant_client_id`, `assistant_user_id` (optional) | While waiting, or when `denied`, `expired` or `cancelled`: the request's `status`. Once `approved`: BotShield records the approval and answers `pairwise_id`, `assistant_name`, `approved_at`, or the error `not_approved` if the approval can't be recorded. |
| `check_assistant` | At every checkout. The person is never asked here. | `partner_user_ref`, `order_ref`, `pairwise_id` (optional, if you kept it), `assistant_client_id`, `assistant_user_id` (optional) | `match` (`true` or `false`, no reason), `checked_at`, `check_id`. |

* `assistant_client_id` is the assistant's Poppy `client_id`, the HTTPS URL of its metadata, from the verified Poppy Session. `assistant_user_id` is the Session's `sub`, when it has one.
* `pairwise_id` is yours to keep. Never give it to the assistant.
* With no approval yet, `check_assistant` answers false: call `request_assistant_approval`.

## API operations

Both need a secret key with Gates API access, as `Authorization: Bearer bs_…`. Errors arrive in `data.error` with HTTP 200, as for the rest of the [Gates API](https://docs.botshield.ai/gate/gates-api.md): `statusCode` in the tables below is a field of `data.error`, not the HTTP status. The check's answer is not signed, so call it only server to server, over TLS, and keep `check_id` with the order. Before you register, ask the account holder with [`gates-api/actions/request`](https://docs.botshield.ai/actions/ask-through-an-agent) (act `assistant:` followed by BotShield's digest of the assistant) and read [`gates-api/actions/request-status`](https://docs.botshield.ai/actions/ask-through-an-agent) until it is `approved`. `AssistantGate` and the MCP tools build that request for you; use them rather than building the act yourself.

### `POST /gates-api/assistants/register`

Records an approved request and returns BotShield's pairwise ID.

| Request field | Description |
| - | - |
| `request_id` | The Actions request the account holder approved. |
| `partner_user_ref` | Your own reference for the verified account. |
| `assistant_client_id` | The assistant's Poppy `client_id`. |
| `assistant_user_id` | Optional. The assistant's user ID for your company (Poppy `sub`). |

```json theme={null}
{
  "data": {
    "data": {
      "pairwise_id": "BA_…",
      "assistant_name": "Example Assistant",
      "approved_at": "2026-11-18T17:02:11.000Z"
    }
  }
}
```

BotShield checks that the request is yours, in your key's environment, and approved; that it names this assistant and this user; that the person who approved holds this account's live BotShield link; and that the title they approved is "Let {name} buy for you" with the name BotShield reads now from the assistant's metadata. Every miss answers the same `not_approved` (404). The call is idempotent: the same approved request returns the same ID. A new approval for the same account and assistant replaces the earlier one, and keeps the same pairwise ID: the ID is derived from your company, the environment, the account, the `client_id` and the user ID.

### `POST /gates-api/assistants/check`

| Request field | Description |
| - | - |
| `partner_user_ref` | The account on the order. |
| `pairwise_id` | Optional. BotShield's ID for the approval, if you kept it. |
| `assistant_client_id` | The assistant's `client_id`. Required without `pairwise_id`. |
| `assistant_user_id` | Optional. The assistant's user ID. It must match the approval: both absent, or both equal. Otherwise the answer is false. |
| `order_ref` | Your reference for this order. Recorded hashed, never echoed. |

```json theme={null}
{
  "data": {
    "data": {
      "match": true,
      "checked_at": "2026-11-20T09:14:03.218Z",
      "check_id": "…"
    }
  }
}
```

`match` carries the answer: `true` means the agent is verified, `false` means it isn't. Verified needs a live approval, this account, the same assistant, and the same user ID (both absent, or both equal).

A request that fails validation (a malformed `pairwise_id`, a `client_id` that isn't a URL, an `order_ref` over 256 characters) returns HTTP 400 with a validation body instead of the `data.error` envelope.

| `code` | `statusCode` | Cause |
| - | - | - |
| `not_approved` | 404 | `register`: there is no approval for this assistant on this account. |
| `assistant_required` | 400 | `check`: send `pairwise_id` or `assistant_client_id`. |
| `not_linked` | 409 | Asking: the account is not BotShield Verified with you. |
| `account_reconfirm_required` | 409 | Asking: the account must be confirmed again before it can be asked. |
| `too_many_open_requests`, `daily_request_limit` | 429 | Asking: 5 open requests, or 50 a day, for one person at your company. |
| `agent_not_found`, `action_not_found`, `action_off` | 404 | Asking: the Trusted Agent or the `assistant` Action is missing or off. |
| `agent_removed_by_person` | 409 | Asking: the person removed this agent, so it can't ask them. |
| `unavailable` | 503 | `register` could not record, or `check` could not answer. A check is never answered `verified: true` without its record. Treat it as false (fail closed), or apply your own fallback, and try again. |
| `invalid_key`, `gates_scope_required`, `org_not_found` | 401, 403, 404 | See [Gates API](https://docs.botshield.ai/gate/gates-api.md). |

Re-asking: with `onUnapproved: 'ask'` (the default), each `require()` without a `BotShield-Approval-Id` after a decline or expiry starts a new request, within the limits above. Use `onUnapproved: 'signal'` to never ask from `require()`, and `ask()` when you choose.

These operations are not in `botshield-sdk` 4.0.1. Call them over HTTP, or use `AssistantGate`.

## What each side learns

| | Learns |
| - | - |
| The assistant | That the account holder was asked, and how it ended. Never the pairwise ID. |
| Your company | Verified, true or false, for each order, and the pairwise ID for the approval. No identifier for the person beyond that pairwise ID. |
| BotShield | That your company asked this account holder to approve this assistant, the answer, and each check's time and result. Never what was bought. |

## Next steps

> [card] [Set up](https://docs.botshield.ai/poppy/setup.md)
>
> Keys, the Trusted Agent, BotShield Verified customers and `poppy.json`.

> [card] [Personal agents (Poppy)](https://docs.botshield.ai/poppy/overview.md)
>
> The two extensions and what each side learns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.