Skip to main content
BotShield tells you that a user is human, never who they are. Results cross to you. Identity does not. This page lists, surface by surface, exactly what you receive, so you can describe the integration accurately to your own privacy and security reviewers.

What you never receive

None of the surfaces on this page sends you any of the following:
  • The human’s name, email address, or phone number.
  • Anything from the way the person unlocks their phone. The passkey is unlocked on the person’s own phone; BotShield never receives a face, a fingerprint, or a template, so it cannot send you one.
  • The human’s device details or location.
  • A score, a confidence value, or a “bot” verdict.
  • A date of birth, an age number, or an “underage” result.
  • An identifier that lets you match a human with another partner’s records. Every handle and opaque ID you receive is specific to you.
You receive no personal data from BotShield. The one thing to watch is data you send yourself: whatever you put in metadata comes back to you in gate webhooks, so keep personal data out of it.

BotShield Gate

Widget events

A gate always asks: every botshield:success follows a passkey confirmation on the phone. No widget event carries an age number or a date of birth, and a Human Gate never carries an age result. (census is the API’s older name for BotShield Gate.)

Inline passkey in your app (Beta)

When your native app runs the person’s passkey inline, POST /request/passkey-options gives you WebAuthn options for that request and the hand-off links, and POST /request/passkey-complete gives you only outcome and an optional code. Neither returns a token, a BotShield ID, a session or anything about the person. You read the result by webhook or GET /verification/status, as for any request.

Attestation token claims

The token from botshield:success is an ES256 JWT that lives 120 seconds. POST /sdk/verify-token returns valid, verdict (pass), replayed, and these claims: The token has no sub claim. It describes the event, not the person. On a met Age Gate the JWT also carries age_over. A token for a Human Gate never carries age_over. A token is meant to be checked once. The first POST /sdk/verify-token records it. A second check is refused with valid: false and replayed: true. See Verify on your server.

Verification status

GET /verification/status returns:

Gate webhooks

event_id is the same value as request_id. environment is development or production. product is census for a request made against a gate. metadata holds only the keys you supplied when you created the request. BotShield’s own request context is not included, and the key is left out when you supplied nothing. reason is one of user_denied, device_lock_required, platform_declined, or internal_error: it describes why the confirmation did not happen, not who the person is. Gate webhooks carry no age result, on either gate type.

Your user reference

If you send platform-user-ref (or partner_user_ref on the server API), BotShield stores a hash of it that is specific to your organization. The reference itself is never returned to you. On a plain gate pass you receive no identifier for the human. The one exception is a person who has linked their account with you: then gate.human_verified also carries that account’s handle, described under Verified Accounts. See BotShield ID.

Verified Accounts

When a person links their account on your platform, you receive a handle: an opaque value that starts with OP_. The handle stays the same for the life of the link, and comes back the same if the person links again. It is specific to your platform, so another platform holds a different value for the same person. No name, email, or phone number travels with a handle. See Verified Accounts and Token and webhooks. A Verified Account and an agent link are separate. The account’s handle is not an Agents Ask opaque_id, linking an account does not link any of your agents, and linking an agent does not link an account.

Age Gate

Age Gate (Beta) is positive-only. It can say that a human is over your threshold. It never says anything else about their age. Age data belongs to Age Gates only. A Human Gate never returns an age result: its token has no age_over claim, and age_verdict and age_source stay null on GET /verification/status, whatever the human’s phone is able to report. unavailable means BotShield could not confirm the threshold. It does not mean the human is under it. There is no “under” value, no date of birth, and no age number on any surface. See Age Gate.

Agents Ask

Agents Ask needs to address the same human more than once, so it uses an opaque ID. The opaque ID starts with OP_ and is pairwise: it is unique to one human and one agent. Two agents that are linked to the same human hold different opaque IDs, so the IDs cannot be matched to each other, to a Verified Account handle, or to any Gate result.

Proof of Resolution claims

A Proof of Resolution is an ES256 JWT that lives 24 hours. See Proof of Resolution.

Agents Ask webhooks

Summary

BotShield ID

How a returning human is recognized without being identified.

Result states

The two result states: a pass, or Unavailable.

Webhook events

Full payloads for every event.

Proof of Resolution

Verify the signed result of an agent action.