> ## 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.

# Trusted Accounts

> Let a real human secure their account on your platform with their BotShield ID, so you know a human runs the account and since when, never who.

A **Trusted Account** is an account on your platform that one real human has bound to their [BotShield ID](/concepts/botshield-id). The person does it once, with a passkey, from an offer you show after they sign in. From then on, every verification on that account tells you that a human is behind it 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.

Trusted Accounts is part of a paid plan. See [pricing](https://botshield.ai/pricing).

## Three parties, three verbs

| Party | Verb | What happens |
| - | - | - |
| The person | **secures** | They tap **Link BotShield ID** on your page and confirm with a passkey in BotShield. |
| Your platform | **trusts** | Your server reads `trusted: true` on the token and the webhook, and can treat the account as run by a human. |
| BotShield | **notarizes** | BotShield records the binding and signs the statement you verify. |

The binding exists only because the person confirmed it. Nothing creates a Trusted Account in the background, and passing a gate never does.

## What you learn and what you never learn

| You learn | You never learn |
| - | - |
| A real human secured this account | Who the human is |
| When the account became trusted (`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. Two platforms cannot compare handles to find the same person.

## One human, one account

On your platform, one BotShield ID secures one account, and one account is secured by one BotShield ID. BotShield refuses anything else:

| Situation | Result |
| - | - |
| The person already secured a **different** account on your platform | Refused with `already_trusted`. They unlink the other account in the BotShield app first. |
| The account is already secured by a **different** BotShield ID | Refused with `rebind_requires_prior_id`. The other ID unlinks first. |
| The same person returns to the account they already secured | No offer is shown. The widget shows the normal verify button, and a pass reports `trusted: true`. |

This is what makes a second account cost a second human.

## How it relates to BotShield Gate

A [gate](/gate/overview) and a Trusted Account answer different questions.

| | BotShield Gate | Trusted 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 |

Three rules connect them:

* **The Console switch decides where the offer appears.** Each Human Gate has a switch in the Console, **Notarize account with BotShield**. Widgets placed with that gate show the offer only while the switch is on. The widget's `notarize="false"` attribute can turn the offer off for one placement. Nothing in your page markup can turn the offer on.
* **The binding belongs to your platform, not to one gate.** The switch chooses which gates carry the offer. After an account is secured, every gate on your platform that receives the same `platform-user-ref` reports `trusted: true` for it. `platform-user-ref` is your stable ID for the account on your platform. BotShield uses it to recognise a Trusted Account.
* **A gate pass never creates or changes a binding.** Passing a gate proves a human is present. Only the person's confirmation on the offer secures an account.

You can place gates and never turn the offer on. An [Age Gate](/gate/age-gate) never shows the offer.

## How it works

<Steps>
  <Step title="You show the offer">
    With the gate's switch on, your page renders the widget after your own sign-in, with your stable ID for the account in `platform-user-ref`, and optionally `account-hint`. The person sees **Secure your account with BotShield**.
  </Step>

  <Step title="The person taps Link BotShield ID">
    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.
  </Step>

  <Step title="The person confirms with a passkey">
    BotShield asks **Secure your account?** and names your platform. The person confirms with their device biometric, or cancels.
  </Step>

  <Step title="You receive the result">
    Your page gets `botshield:success` with `trusted: true`. Your server verifies the token, and your webhook endpoint receives `gate.human_verified` with `trusted: true` and `first_time: true`.
  </Step>
</Steps>

<Tip>
  The [BotShield Demos](https://demo.botshield.ai) run BotShield Gate and Agents Ask on production keys. To run the Trusted Accounts confirmation yourself, use **Trusted Accounts**, then **Try it** in the [BotShield Console](https://console.botshield.ai).
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/trusted-accounts/quickstart">
    Turn on the offer, add the widget and verify the result.
  </Card>

  <Card title="Widget reference" icon="code" href="/trusted-accounts/widget">
    Attributes, events, card states and failure reasons.
  </Card>

  <Card title="Token and webhooks" icon="file-signature" href="/trusted-accounts/token-and-webhooks">
    The trust claims and the events your server receives.
  </Card>

  <Card title="Managing accounts" icon="list-check" href="/trusted-accounts/manage-accounts">
    The registry, Revoke, and what the person can do.
  </Card>
</CardGroup>