> ## Documentation Index > Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt > Use this file to discover all available pages before exploring further. # Verified Accounts > Let a person link their account on your platform with their BotShield ID and a passkey, so you know a real human runs the account and since when, never who. A **Verified Account** is an account on your platform that a person has linked to their [BotShield ID](https://docs.botshield.ai/concepts/botshield-id.md). 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](https://botshield.ai/pricing). > [!NOTE] > > 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 | Party | Verb | What happens | | - | - | - | | The person | **links** | They tap **Link with BotShield ID** on your page and confirm with a passkey in BotShield. | | Your platform | **trusts** | Your server reads `trusted: true` on the token, and `account.secured` on your webhook, and can treat the account as run by a human. | | BotShield | **notarizes** | BotShield records the link and signs the statement you verify. | The link exists only because the person confirmed it. Nothing links an account in the background. ## What you learn and what you never learn | You learn | You never learn | | - | - | | A real human linked this account | Who the human is | | When the account was linked (`trusted_since`) | Their name, email address or phone number | | When the human last passed (`last_pass_at`) | Their device, location or activity | | An opaque handle for the account, `OP_` followed by 12 characters | Their BotShield ID, or any account they hold on another platform | 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`: | Situation | Result | | - | - | | The person already linked a **different** account on your platform | Refused with `already_trusted`. They unlink the other account in the BotShield app first. | | The account is already linked by a **different** BotShield ID | Refused with `rebind_requires_prior_id`. That ID unlinks first, or you revoke the link in the Console. | | The same person returns to the account they already linked | Not an error. The widget shows the account as linked, and a pass reports `trusted: true`. | 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. ## Where a link is made A link is always made by the person, with a passkey, on a page you control. There are three places it can happen: | Place | Where you turn it on | Your page | | - | - | - | | **A Link with BotShield ID surface** | In the Console, **Verified Accounts**, then **Set up Link with BotShield ID**. A surface is a page such as your sign-in or account settings, with one site key. This is the main path. | `` with that site key. No gate is needed. | | **A gate whose link setting is on** | The gate's **link** setting: `required`, `optional` or `never`. See [Linking at a gate](https://docs.botshield.ai/gate/link.md). | The gate's widget, with `platform-user-ref`. A `required` gate refuses a request without it. | | **A BotShield Action** | An action always stands on a Verified Account, so the first tap links the account. See [BotShield Actions](https://docs.botshield.ai/actions/overview.md). | The action request, with your user reference. | 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](https://docs.botshield.ai/gate/overview.md) and a Verified Account answer different questions. | | BotShield Gate | Verified Accounts | | - | - | - | | Question | Is a real human here, at this action? | Is this account run by a real human? | | Lasts | One action | Until the person unlinks or you revoke | | Created by | Every verification | One passkey confirmation by the person | * **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](https://docs.botshield.ai/verified-accounts/lifecycle.md) 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`. > [!TIP] > > To run the confirmation yourself, open **Verified Accounts**, then **Try it** in the [BotShield Console](https://console.botshield.ai). You act as your own customer, against your Development key. ## Next steps > [card] [Quickstart](https://docs.botshield.ai/verified-accounts/quickstart.md) > > Turn on the offer, add the widget and verify the result. > [card] [Account lifecycle](https://docs.botshield.ai/verified-accounts/lifecycle.md) > > Link, status, unlink and link again, and who can do each. > [card] [Server API](https://docs.botshield.ai/verified-accounts/server-api.md) > > Read the status, list the registry, and unlink with your API key. > [card] [Staying in sync](https://docs.botshield.ai/verified-accounts/staying-in-sync.md) > > Know an account's current state, live in the page and pushed to your server. > [card] [Widget reference](https://docs.botshield.ai/verified-accounts/widget.md) > > Attributes, events, chip states and failure reasons. > [card] [Token and webhooks](https://docs.botshield.ai/verified-accounts/token-and-webhooks.md) > > The trust claims and the events your server receives. > [card] [Managing accounts](https://docs.botshield.ai/verified-accounts/manage-accounts.md) > > The registry, Revoke, and what the person can do. > [card] [Not OAuth](https://docs.botshield.ai/verified-accounts/not-oauth.md) > > What this protocol is, and what it is not. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.