Skip to main content
When the inline passkey can’t run, the person confirms in BotShield instead. This is the hand-off every BotShield request supports, and the way through on every inline failure. Use it when:
  • your app isn’t registered, or runs on Android today;
  • the request is for an Age Gate;
  • passkey-options answered fallback or failed;
  • the device has no BotShield passkey, or the person cancelled and chose Use the BotShield app instead;
  • the person is on a computer and has BotShield on their phone.
Use the request’s https link: Both open https://app.botshield.ai/verify?request_id=…. Prefer the https link to deep_link (botshield://…). The https link works whether or not the app is installed. deep_link fails silently without the app.
On iPhone, iOS opens another app only from a real tap. Open the link straight from the person’s tap on Open BotShield. If you fetch the request first and open the link after the await, iOS may refuse. Fetch the request before you show the button.

On this phone

1

Show an Open BotShield button

Label it Open BotShield or Use the BotShield app instead.
2

Open the link outside your app

Open the URL with the system, not in an in-app web view, so iOS and Android can hand it to the BotShield app.
3

The person confirms in BotShield

BotShield names your platform and asks the person to confirm with their passkey.
4

The person comes back

BotShield doesn’t send the person back to your app automatically. They return with the app switcher, or the back link iOS shows in the corner. When your app is active again, check the result.

From another screen (QR code)

On a tablet, a computer or a TV, draw web_url as a QR code with your own QR library. The person scans it with their phone camera and confirms in BotShield. Keep the QR code up until the request completes or expires_at passes. When the person has secured their account with you and you sent partner_user_ref, BotShield also pushes the request to their phone. pushed_to_devices above 0 means it did: tell them to check their phone, and keep the QR code as a fallback.

Learn the result

The hand-off gives your app nothing back. Your server learns the result:
  • Webhook (preferred): gate.human_verified or gate.unavailable, matched by request_id.
  • Polling: GET /verification/status?request_id=… every 3 to 5 seconds until it’s final or expires_at passes.
When the app becomes active again, ask your server whether the request completed. Then check the token on your server before you let the action through. If expires_at passes with no result, treat the request as Unavailable. No webhook is sent for a request nobody opened.

What to show

See Result states for every reason.