> ## 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 4.0

> What changed for developers in BotShield 4.0: key options and send-only keys, server-confirmed links, stricter token checks, new webhook events, and development key limits.

> [!NOTE]
>
> BotShield 4.0 is live in production as of November 2026. This page lists the changes that affect an integration. Each item links to the page with the details.

## Changes to check before you upgrade

These can change what an existing integration sees.

| Change | What to do |
| - | - |
| `POST /sdk/verify-token` needs your API key. A call without one returns `valid: false` with `code: "secret_key_required"`. | Call it from your server with `Authorization: Bearer bs_…`. See [API overview](https://docs.botshield.ai/api-reference/overview.md#which-operation-takes-which-credential). |
| A token issued in one environment fails a check made with the other environment's key. A sandbox pass never passes a production check. | Check development tokens with a development key and production tokens with a production key. |
| `GET /verification/status` returns the verification tokens only to the caller that may read them. Everyone else sees `null` in `verification_token` and `signed_token`. The status itself is unchanged. | For a request your server started, read the status with your API key from the same environment. See [Result states](https://docs.botshield.ai/concepts/result-states.md#the-verification-status-enum) and [Verify on your server](https://docs.botshield.ai/gate/verify-on-your-server.md). |
| A `live` site key with no allowed origins is refused on every request. | Add your site's origin to the key under **Settings → Developer Tools → Site Keys**. See [Allowed origins](https://docs.botshield.ai/console/keys-and-environments.md#allowed-origins). |
| A session opened with a site key cannot write a new Verified Account link (`link_requires_server_session`), and a request cannot name a different account from its session (`account_override_refused`). | Open the session from your server with your API key, naming the signed-in customer. See [Errors](https://docs.botshield.ai/api-reference/errors.md#botshield-gate). |
| Making accounts BotShield Verified in Production needs a verified business (`org_not_verified`). | Finish business verification in the Console, or use a development key meanwhile. |
| Creating a production API key asks for your Developer passkey. | No code change. See [Passkey confirmation](https://docs.botshield.ai/console/keys-and-environments.md#passkey-confirmation). |

## Keys and the Console

* **Key options.** Each API key now has three options under **Settings → Developer Tools → API Keys**: **Admin API access**, **Gates API access**, and **a link waits for my server's confirm**. Gates API access grants the `gates:write` scope, and turning it on for a production key asks for your passkey. See [Key options](https://docs.botshield.ai/console/keys-and-environments.md#key-options).
* **A link waits for my server's confirm.** A per-key option on API keys and site keys. When it is on, a Verified Accounts link stays pending after the person's tap until your server confirms the account with `POST /sdk/confirm-link`. Keys created before 4.0 start with it off; new keys start with it on. See [A link waits for your server's confirm](https://docs.botshield.ai/console/keys-and-environments.md#a-link-waits-for-your-servers-confirm).
* **Send-only keys.** A production API key for a CRM or other automation. It sends a request to verify with `POST /sdk/send-by-number` and reads the outcome of what it sent, and every other operation refuses it. See [Send-only keys](https://docs.botshield.ai/console/keys-and-environments.md#send-only-keys).

## API

* **New:** `POST /sdk/confirm-link` confirms a waiting link. `POST /sdk/verify-token` with `partner_user_ref` confirms it the same way. Error codes are in [Errors](https://docs.botshield.ai/api-reference/errors.md#confirming-a-waiting-link).
* **New:** `POST /sdk/send-by-number` sends a request to verify for a BotShield Action to a person by phone number, from your server.
* **`POST /sdk/verify-token`:** send `expected_request_id` to have BotShield refuse a token for any other request (`code: "request_mismatch"`). A refused check does not use up the token. To check a token without spending it, verify its signature locally against the [JWKS](https://docs.botshield.ai/api-reference/overview.md#verify-signatures-locally).
* **`GET /verification/status`:** a request that started a link carries `link_state` (`pending`, `live`, `expired` or `refused`), and `link_code: "link_pending"` with `link_expires_at` while the link waits.

## Rate limits

* Development keys keep their limits: 10 requests a minute, 100 an hour, 300 a day, and one request at a time. The limits now also apply to the widget's calls that carry a `pk_test_…` key in the request rather than in the `Authorization` header. Those calls return the error inside `data.error` with `statusCode` 429 and `code: "RATE_LIMITED"`. See [Development keys are for testing](https://docs.botshield.ai/api-reference/rate-limits.md#development-keys-are-for-testing).
* New error code `RATE_LIMIT_UNAVAILABLE` (HTTP 403, "Busy right now — try again in a few seconds."). It is sent only on calls a person makes, such as signing in or answering a passkey prompt, when BotShield cannot count them for a moment. See [When BotShield is busy](https://docs.botshield.ai/api-reference/rate-limits.md#when-botshield-is-busy).

## Webhooks

* **New events:** [`account.link_pending`](https://docs.botshield.ai/webhooks/events#account-link_pending) (a person tapped and the link waits for your confirm) and [`account.link_live`](https://docs.botshield.ai/webhooks/events#account-link_live) (your server confirmed it). An endpoint with an event filter must add them to receive them.
* **`account.secured`** is sent when your server confirms the link, beside `account.link_live`, for keys with **a link waits for my server's confirm** on. For other keys it is sent at the tap, as before.
* **`gate.human_verified`** carries `link_state: "pending"`, with `trusted: false` and no `handle`, when the confirmation left a link waiting.
* **`gate.unavailable`** has two new refusals: `failure_code: "number_required"` (the person's BotShield ID has no verified phone number) and `failure_name: "account_limit_reached"` beside `failure_code: "already_trusted"` (the person has reached the number of accounts you allow).

See [Webhook events](https://docs.botshield.ai/webhooks/events.md) for every payload.

## Product pages

The 4.0 changes to each product are on its own pages:

> [card] [BotShield Gate](https://docs.botshield.ai/gate/overview.md)
>
> Placing gates, the widget, and the Gates API.

> [card] [Verified Accounts](https://docs.botshield.ai/verified-accounts/overview.md)
>
> BotShield Verified accounts, server-confirmed links, and the account registry.

> [card] [BotShield Actions](https://docs.botshield.ai/actions/overview.md)
>
> Asking a BotShield Verified customer to confirm an act.

> [card] [Agents Ask](https://docs.botshield.ai/agents-ask/overview.md)
>
> Agents that ask the account holder to confirm.

> [card] [TypeScript SDK](https://docs.botshield.ai/sdk/typescript.md)
>
> The server SDK.

> [card] [Keys and environments](https://docs.botshield.ai/console/keys-and-environments.md)
>
> Keys, key options, and production requirements.


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