Skip to main content
A result in the browser is a hint. The decision belongs on your server. There are two patterns:
  • Pattern A: verify the widget’s result. The web component runs the verification and your server checks the token or request ID it produced.
  • Pattern B: server-to-server. Your server creates the verification request, you show the link in your own UI, and you learn the result by webhook or polling.
All calls go to https://api.botshield.ai/operations. Every operation answers HTTP 200 with a data envelope, and handler errors arrive inside it as data.error, also with HTTP 200. Check data.error before you read the payload. See API overview and Errors.
TypeScript SDK. Pass serverURL when you construct the client; the package does not default to production. apiKeyAuth is sent as the Authorization header exactly as you give it, so include the Bearer prefix. The SDK does not unwrap the envelope, and it uses camelCase field names. See TypeScript SDK.

Pattern A: verify the widget’s result

The widget’s botshield:success event gives your page a request_id and a token. Every gate asks, so every success follows a passkey confirmation and carries a signed token. The token is a JWT; it is never a request ID. Send both to your server with the action they protect.

The verification token

The token describes the event, never the person. It has no subject, no user ID and no email. It also has no gate claim: see What to check.

Verify the token

POST /sdk/verify-token needs no API key. The token is the proof. Send your Organization ID as audience, and a token issued for any other organization comes back valid: false with the reason “Token was issued for a different organization.”You can also send your secret API key as Authorization: Bearer bs_…. The check is then for the key’s organization, whatever audience says. An invalid key is refused with valid: false and the reason “Invalid API key — check the key, or call without one.”Each token answers valid: true once. See Single use.
(census is the API’s name for BotShield Gate.) From botshield-sdk 2.1.0 the SDK sends audience and types verdict and replayed; 2.2.1 adds claims.act. On 2.0.x, which has no audience, compare claims.organizationId with your Organization ID yourself.A valid token:
An expired or invalid token still answers HTTP 200, with valid: false:
For a bad signature, reason is "Invalid token — signature verification failed" and there are no claims.

Single use

A token is valid for one check. This is a platform rule, not a setting: no gate, organization or key turns it off. A second check:
When the store that records checks cannot answer, BotShield refuses the check rather than guess (it fails closed):
Retry with the same token. Because the failed check did not mark it used, a retry can still answer valid: true, as long as the token has not expired (120 seconds after issue). What this means for your integration:
  • Check each token in one place, on your server. If your page or a second service also calls verify-token, whichever calls first uses the check, and the other gets replayed: true.
  • Keep the first answer. If your server needs the claims again, store them from the first check. Do not call verify-token twice.
  • Treat replayed: true as a refusal. It means this token has already been used, possibly by someone else.
  • An expired token, a bad signature, or a token for another organization does not use the check.

When there is no token

A completed request almost always carries a token. If botshield:success arrives with token: null, confirm the request from your server with GET /verification/status, which needs no API key:
The status response also carries verification_token once the request is completed, so you can verify that token as above.

What to check

verify-token needs no credentials. Without audience or an API key it answers valid: true for a genuine token issued for any organization, and a local signature check without an audience does the same. So a valid signature is only the first test. Before you let the action through, confirm all of these on your server:
  1. The token verifies (signature, issuer, not expired), or the status is completed.
  2. The token is for your organization: you passed audience or your API key, or organization_id is yours. Copy your Organization ID from Settings → Developer Tools → API Keys in the Console and keep it in your configuration. A create-session response carries the same value as organization.id.
  3. The token is fresh: verify-token answered valid: true, which it does once per token. The request_id belongs to this action. In Pattern B, compare it with the request you created. In both patterns, record every request_id you accept and reject repeats, so one verification cannot be replayed for many actions.
  4. On a BotShield Action, claims.act is exactly the act string you expect.
  5. The gate is the one you expect. The token carries no gate claim, so if you run several gates, or both environments, read GET /verification/status and compare scope with your gate key and metadata.environment with production.

Pattern B: server-to-server

Use this when you draw your own UI, for a native app, a kiosk, or a back-office flow. Every request asks the person to confirm with a passkey on their phone, and the gate’s Who may pass levers apply. Server-to-server verifications count in the gate’s Overview metrics in the Console, the same as widget verifications.
1

Create a session

Call POST /sdk/create-session with your API key: bs_dev_… for Development gates, bs_production_… for Production gates. BotShield resolves the gate in the environment of the key that calls it, so the same gate key can exist in Development and in Production as two independent gates.
The same three values are also returned under the older names session_token, expires_at and expires_in_seconds. The grant token lives 5 minutes and works once: the next step consumes it. It only authorizes creating one verification request; it is not a user session.
2

Create the verification request

Call POST /sdk/create-verification-link with the grant token as the Bearer credential, not your API key.
Errors arrive as data.data.error with HTTP 200:
3

Show the link to the user

On desktop, render web_url as a QR code with your own QR library and ask the user to scan it with their phone camera. On mobile, open web_url or deep_link. The user needs a BotShield ID — web_url opens the BotShield web app (public beta), where a first-time user creates a passkey with no download; deep_link opens the BotShield app if they have it. They confirm with a passkey and are handed back to what they were doing.
In a native app, the person can confirm without leaving it. See Inline passkey in your app. The hand-off on this page stays the fallback: see Open BotShield.
4

Learn the result

Add an endpoint in the Console under Settings → Developer Tools → Webhooks and subscribe to gate.human_verified and gate.unavailable. Match the delivery to your request by request_id.
One endpoint receives deliveries from both environments, so branch on the top-level environment (development or production). metadata holds only the keys you supplied. Verify the signature on every delivery, and treat deliveries as at-least-once. See Webhooks and Webhook events for the full payloads and the gate.unavailable reasons.
Keep your own timer. BotShield sends gate.unavailable when the BotShield app reports a failure, for example when the person cancels the passkey prompt, when a request that was opened fails, and when the gate’s levers refuse the person (with failure_code). If the user never opens the link, the request simply expires and no webhook is sent. When expires_at passes with no gate.human_verified, treat the request as Unavailable.

Status values

verification/status returns its payload directly under data, with no second data level. The status response never contains identity fields. It reports the request, not the person. Records from before BotShield 3.3 can also read pass, an instant pass that no longer exists; treat it as Verified.

The 409 case

BotShield allows one pending request per user and gate. The user is the partner_user_ref you send to create-verification-link, or else the partner_user_id you sent to create-session. While that user has a pending, unexpired request for the gate, a second create-verification-link for the same gate returns:
If the user abandoned the first request, revoke it with your API key and start again from create-session (the grant token you used for the rejected call is still unused, so you can also reuse it within its 5 minutes).
Revoking expires the pending requests immediately. revoke-verification clears exactly the requests the 409 rule matches, the pending, unexpired ones for that user and gate, and returns how many in revoked_count. Pass the same identifier in partner_user_id that the request was created with. A completed or failed request never blocks a new one, so you can ask the same user to verify at the same gate again as soon as the last request finishes. The rule applies only when the request names a user: leave partner_user_id off create-session and partner_user_ref off create-verification-link if you do not need it. It also does not apply to requests the web component makes with a site key.

Next steps

Webhooks

Add an endpoint and verify deliveries.

TypeScript SDK

Install and configure botshield-sdk.

Age Gate

Read the age result on your server.

Errors

The error envelope and status codes.