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:writescope, 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-numberand reads the outcome of what it sent, and every other operation refuses it. See Send-only keys.
API
- New:
POST /sdk/confirm-linkconfirms a waiting link.POST /sdk/verify-tokenwithpartner_user_refconfirms it the same way. Error codes are in Errors. - New:
POST /sdk/send-by-numbersends a request to verify for a BotShield Action to a person by phone number, from your server. POST /sdk/verify-token: sendexpected_request_idto 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 carrieslink_state(pending,live,expiredorrefused), andlink_code: "link_pending"withlink_expires_atwhile 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 theAuthorizationheader. Those calls return the error insidedata.errorwithstatusCode429 andcode: "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) andaccount.link_live(your server confirmed it). An endpoint with an event filter must add them to receive them. account.securedis sent when your server confirms the link, besideaccount.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_verifiedcarrieslink_state: "pending", withtrusted: falseand nohandle, when the confirmation left a link waiting.gate.unavailablehas two new refusals:failure_code: "number_required"(the person’s BotShield ID has no verified phone number) andfailure_name: "account_limit_reached"besidefailure_code: "already_trusted"(the person has reached the number of accounts you allow).
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.
