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

# The link setting

> Decide whether a pass at a gate links the person's BotShield ID to your account for them: required, optional or never.

A gate's `link` setting decides whether a pass also links the person to your account for them, making it a [Secured Account](https://docs.botshield.ai/secured-accounts/overview.md). It is part of the gate's [policy document](https://docs.botshield.ai/gate/gates-api.md#the-policy-document).

| `link` | What a pass does |
| - | - |
| `required` | Every pass links the person to the account you name. You must send your own user ref with each request. A request without one is refused. |
| `optional` | A pass links the person when you send your user ref. Without a ref, the pass is anonymous. |
| `never` | No pass links anyone. BotShield does not keep your user ref with the request. |

## Set it

> [tab] Console
>
> When you [place a gate](https://docs.botshield.ai/gate/place-a-gate.md#place-the-gate), choose under **Who may pass** › **Link their account when they pass**: **required**, **when you send your user ref** (`optional`) or **never**. A preset pre-fills it: **Presale** and **Promo** pre-fill **required**, the other presets and **BotShield Gate** (Custom) pre-fill **when you send your user ref**.
>
> To change it later, open the gate and change the same row in its **Configuration** card, then select **Save**. On a Production gate, confirm with your Developer passkey.
>
> An Age Gate has no link row: it never links.

> [tab] Gates API
>
> Set `policy.link` when you [place a gate with the Gates API](https://docs.botshield.ai/gate/gates-api.md#create-a-gate). A `preset` pre-fills it the same way as in the Console.
>
> ```json theme={null}
> {
>   "key": "drop-dec-04",
>   "name": "Drop · Dec 4",
>   "preset": "drop",
>   "policy": { "link": "required" }
> }
> ```

A gate placed with the Gates API with no preset and no `link` reads as `never`. A gate placed before release 3.4, whose document has no `link`, follows its older secure-accounts switch: on reads as `optional`, off reads as `never`. An organization-wide document can tighten every gate: `required` is tighter than `optional`, which is tighter than `never`.

## What the person sees

The person is told before a pass links them. When a pass will link them and their BotShield ID is not yet linked to your account, the card in the BotShield app says the pass links them with your company, before they confirm. A person who is already linked is not told again.

The link happens in the same passkey confirmation as the pass. There is no second tap and no separate step. When the confirmation completes, the pass and the link are recorded together.

What you learn is the same as for any Secured Account: the token carries `trusted: true` with `trusted_since` and `last_pass_at`, and never the person's identity. See [Token and webhooks](https://docs.botshield.ai/secured-accounts/token-and-webhooks.md).

## Send your user ref

Your user ref is your own stable identifier for the signed-in user, such as your internal user ID. BotShield stores it only as a one-way hash. Use an opaque ID, never an email address.

> [tab] Widget
>
> Set `platform-user-ref` on the element:
>
> ```html theme={null}
> <botshield-verify
>   site-key="pk_live_…"
>   scope="presale-dec-04"
>   platform-user-ref="usr_48121"
> ></botshield-verify>
> ```

> [tab] Server
>
> Send `partner_user_ref` to `POST /sdk/create-verification-link`, or `partner_user_id` to `POST /sdk/create-session`. When both are set, `partner_user_ref` is used.
>
> ```bash curl theme={null}
> curl -s https://api.botshield.ai/operations/sdk/create-verification-link \
>   -H "Authorization: Bearer bss_5e1c…" \
>   -H "Content-Type: application/json" \
>   -d '{"gate":"presale-dec-04","mode":"private","partner_user_ref":"usr_48121"}'
> ```
>
> The response carries `notarize: true` when this pass will link the person, and `trusted: true` when the user ref is already linked.

## `required` needs a user ref

On a `link: required` gate, a request without a user ref is refused before anything is shown to the person:

```json theme={null}
{
  "data": {
    "error": {
      "message": "This gate links each person to your account for them — send your own user ref (platform-user-ref) with the request.",
      "statusCode": 400,
      "code": "link_requires_user_ref"
    }
  }
}
```

The widget reports the same refusal on `botshield:failure`, with `code` and `message` in `detail`:

```json theme={null}
{
  "reason": "modal_create_failed",
  "code": "link_requires_user_ref",
  "message": "This gate links each person to your account for them — send your own user ref (platform-user-ref) with the request."
}
```

`reason` is `mobile_create_failed` on a phone. Widget versions before 3.0.15 report only `reason`. See [Widget versions](https://docs.botshield.ai/gate/widget-versions.md).

If the setting changes to `required` while a request is open, BotShield checks again when the person confirms. A pass that did not run the linking confirmation is then refused: the request ends `failed` and `gate.unavailable` carries `failure_code: "link_requires_user_ref"`.

On a `required` gate the page cannot opt out: `notarize="false"` has no effect. On an `optional` gate, `notarize="false"` keeps that placement's passes anonymous. See [Secured Accounts widget](https://docs.botshield.ai/secured-accounts/widget.md).

## An Age Gate never links

An [Age Gate](https://docs.botshield.ai/gate/age-gate.md) always reads as `link: never`, whatever its document or the organization's says. The age answer is read on the person's phone and is never tied to an account. This is a platform rule, not a setting.

## Choose a setting

| Your page | Use |
| - | - |
| Only signed-in users reach the gate, and you want every pass tied to an account, for example a presale for registered fans. | `required` |
| Signed-in and signed-out users share the page. | `optional` |
| You want no account tie at all, or the gate is an Age Gate. | `never` |

## Next steps

> [card] [Gates API](https://docs.botshield.ai/gate/gates-api.md)
>
> Place a gate with its policy document.

> [card] [Secured Accounts](https://docs.botshield.ai/secured-accounts/overview.md)
>
> What a link gives you, and what it never does.


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