Skip to main content
A Verified Account is an account on your platform that a person has linked to their BotShield ID. The person does it once, with a passkey, from the Link with BotShield ID chip you show after they sign in. From then on, BotShield can tell you that a real human runs the account and since when. BotShield tells you that a human runs the account, never who. You receive no name, no email address and no device information. Verified Accounts is part of a paid plan. See pricing.
Verified Accounts was called Trusted Accounts before release 3.3, and Secured Accounts in 3.3. Only the name changed. Field names, event names, API paths and SDK names keep their older spelling: trusted: true on the token, the account.secured event, POST /secured-accounts/revoke, and client.securedAccounts in the SDK.
We only verify human. A Verified Account tells you a real person runs the account. It never tells you who.

Three parties, three verbs

The link exists only because the person confirmed it. Nothing links an account in the background.

What you learn and what you never learn

The handle is different on every platform, so two platforms cannot compare handles to find the same person. On your platform it stays the same for the same person, including after they unlink and link the account again.

One BotShield ID, one account

On your platform, one BotShield ID links one account, and one account is linked by one BotShield ID. BotShield refuses anything else with a 409: An active link is never overwritten. From release 3.3 the refusals also carry plain names: account_already_secured_here and account_held_by_another_id.

Development and Production

A link belongs to the environment of the site key its confirmation ran under. A pk_test_... key makes Development links and a pk_live_... key makes Production links. The two never meet: a Development link never counts as linked, or as a conflict, in Production. A link is always made by the person, with a passkey, on a page you control. There are three places it can happen: The Console setting is the authority. Your page markup cannot turn the offer on, and notarize="false" turns it off for one placement on an optional offer. In Production the Console asks for your Developer passkey before the switch changes. A gate with an age threshold never offers it.

How it relates to BotShield Gate

A gate and a Verified Account answer different questions.
  • The link belongs to your platform, not to one gate. After an account is linked, a verification on any of your gates that sends the same platform-user-ref reports trusted: true. platform-user-ref is your stable ID for the account. BotShield uses it, hashed, to recognise a Verified Account.
  • A plain gate pass never creates or changes a link. Passing a gate proves a human is present. Only the person’s confirmation on a link offer links an account, and the person is told before it happens.

Your responsibilities

BotShield verifies the human. Your platform owns the account. To keep the link meaningful:
  1. Send a stable reference. platform-user-ref is your internal user ID: it never changes for the account and is never an email address or anything the user can edit.
  2. Show the offer only after your own sign-in. The link says the person confirming is the one using this account, so your sign-in or a fresh re-authentication comes first.
  3. Verify on your server. Treat the browser event as a hint. Check the token with POST /sdk/verify-token and read trusted there.
  4. Store the handle. Keep the handle from account.secured beside your user. It is how every later event and API call names the account.
  5. Unlink when a sign-in detail changes. When the email, password, phone or MFA on the account changes, call POST /secured-accounts/revoke with reason: "credential_changed". The person links again behind your own re-authentication. Unlink also when the account is closed or changes hands.
  6. Handle account.unlinked. The person can unlink at any time in the BotShield app. Mark the account as no longer verified when the event arrives, and reconcile with GET /secured-accounts/list if you miss one.
  7. Keep Development apart. Account events carry no environment field. Do not let a Development link change production data.
See Account lifecycle for every state and transition.

How it works

1

You show the chip

After your own sign-in, your page renders the widget with your stable ID for the account in platform-user-ref. The widget draws the Link with BotShield ID chip.
2

The person taps the chip

On a phone the tap opens BotShield. On a desktop it opens BotShield in a new tab, or shows a QR code and a 6-character code to use from a phone. The code lasts 5 minutes and works once.
3

The person confirms with a passkey

BotShield names your platform and asks the person to confirm with their passkey. The passkey prompt appears in BotShield, never on your page. The person can also cancel.
4

You receive the result

Your page gets botshield:success with trusted: true. Your server verifies the token. Your webhook endpoint receives account.secured with the account’s handle, and gate.human_verified with trusted: true and first_time: true.
To run the confirmation yourself, open Verified Accounts, then Try it in the BotShield Console. You act as your own customer, against your Development key.

Next steps

Quickstart

Turn on the offer, add the widget and verify the result.

Account lifecycle

Link, status, unlink and link again, and who can do each.

Server API

Read the status, list the registry, and unlink with your API key.

Staying in sync

Know an account’s current state, live in the page and pushed to your server.

Widget reference

Attributes, events, chip states and failure reasons.

Token and webhooks

The trust claims and the events your server receives.

Managing accounts

The registry, Revoke, and what the person can do.

Not OAuth

What this protocol is, and what it is not.