Skip to main content
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.

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

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

Webhooks

  • New events: account.link_pending (a person tapped and the link waits for your confirm) and 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 for every payload.

Product pages

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

BotShield Gate

Placing gates, the widget, and the Gates API.

Verified Accounts

BotShield Verified accounts, server-confirmed links, and the account registry.

BotShield Actions

Asking a BotShield Verified customer to confirm an act.

Agents Ask

Agents that ask the account holder to confirm.

TypeScript SDK

The server SDK.

Keys and environments

Keys, key options, and production requirements.