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

# Secured Accounts

> Let a person secure 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 **Secured Account** is an account on your platform that a person has linked to their [BotShield ID](/concepts/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.

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

<Note>
  Secured Accounts was called Trusted Accounts before release 3.3. Only the name on screen changed. Field names, event names and operation names keep their `trusted` spelling, for example `trusted: true` on the token.
</Note>

## Three parties, three verbs

| Party | Verb | What happens |
| - | - | - |
| The person | **secures** | 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 secures an account in the background.

## 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 was secured (`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 secure the account again.

## One BotShield ID, one account

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

| 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`. That ID unlinks first, or you revoke the link in the Console. |
| The same person returns to the account they already secured | Not an error. The widget shows the account as secured, 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 secured, or as a conflict, in Production.

## Where the offer appears

You turn the offer on in the [BotShield Console](https://console.botshield.ai), in one of two places:

| Place | Where in the Console | Your page |
| - | - | - |
| **A Link with BotShield ID surface** | **Secured Accounts**, then **Link with BotShield ID**, then **Set up Link with BotShield ID**. A surface is a page such as your sign-in or account settings, with one site key. | `<botshield-verify notarize platform-user-ref="...">` with that site key. No gate is needed. |
| **A Human Gate** | **BotShield Gate**, select the gate, then the **Link with BotShield ID** switch in its **Configuration** card. | `<botshield-verify scope="<gate key>" platform-user-ref="...">`. |

In both places the Console switch is the authority. Your page markup cannot turn the offer on, and `notarize="false"` turns it off for one placement. In Production the Console asks for your Console passkey before the switch changes. An [Age Gate](/gate/age-gate) never offers it.

## How it relates to BotShield Gate

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

| | BotShield Gate | Secured 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 secured, 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 Secured 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 the offer secures an account.

## How it works

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

<Tip>
  To run the confirmation yourself, open **Secured Accounts**, then **Try it** in the [BotShield Console](https://console.botshield.ai). You act as your own customer, against your Development key.
</Tip>

## Next steps

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

  <Card title="Staying in sync" icon="arrows-rotate" href="/secured-accounts/staying-in-sync">
    Know an account's current state, live in the page and pushed to your server.
  </Card>

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

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

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

  <Card title="Not OAuth" icon="code-compare" href="/secured-accounts/not-oauth">
    What this protocol is, and what it is not.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.