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

# Confirm links on your server

> On a key whose links wait for your server, a link goes live only when your server names the account its own session shows, with your secret API key.

From BotShield 4.0, a link can wait for your server. The person taps **Get BotShield Verified** and confirms with their passkey in BotShield, and the link is then **pending**. It goes **live** only when your server tells BotShield which account it is for, with your secret API key, and BotShield finds that it is the same account the link was started for.

This closes a gap a page cannot close by itself. The browser names the account in `platform-user-ref`, and anything in the browser can be changed. Your server knows which account is signed in. The confirm lets your server check the link before it counts.

## Which keys wait

**A link started on your page always waits.** Get BotShield Verified runs with your site key, and its link waits for your server's confirm on every key, including keys created before 4.0. A site key alone never makes an account BotShield Verified.

**A request your server starts** follows its secret API key's setting, **a link waits for my server's confirm**:

| API key | Setting |
| - | - |
| Created in BotShield 4.0 or later | On |
| Existed before 4.0 | Off: its links go live at the tap. Turn it on. |

Change the setting for an API key in the [BotShield Console](https://console.botshield.ai) under **Settings**, **Developer Tools**. Only an organization admin can change it, and for a Production key the Console asks for your Developer passkey first. Links that were live before you turned the setting on stay live.

## The flow

**1. The person taps and confirms**

Your page shows **Get BotShield Verified** with your user ID in `platform-user-ref`. The person confirms with their passkey in BotShield. BotShield tells them it is finishing with your company.

**2. BotShield tells you a link is waiting**

Your page receives `botshield:success` with the `request_id`, `token: null` and `trusted: false`. Your webhook endpoint receives `account.link_pending` with the same `request_id`. Nothing is BotShield Verified yet. No handle is sent, and the account is not in your registry as BotShield Verified.

**3. Your server confirms**

Your page sends the `request_id` to your own server, inside the person's signed-in session. Your server calls `POST /sdk/confirm-link` with its secret API key, the `request_id`, and the user ID **that session** shows.

**4. The link goes live**

When the account matches, the link is live. The response carries the account's `handle` and the finished token, and your endpoint receives `account.link_live` and `account.secured`. The widget on your page shows **BotShield Verified** within a few seconds.

A link that is not confirmed within **24 hours** of the tap expires. Nothing becomes BotShield Verified, and the person can start again from your page.

## Where the confirm runs

Run the confirm in a request that carries the person's signed-in session on your side, so the account you send is the one your session shows, not one the browser named.

```html theme={null}
<script>
  const widget = document.querySelector('botshield-verify');

  widget.addEventListener('botshield:success', async (e) => {
    // On a key whose links wait for your server: token is null, trusted is false.
    await fetch('/api/botshield/confirm', {
      method: 'POST',
      credentials: 'same-origin',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ request_id: e.detail.request_id }),
    });
  });
</script>
```

Your `/api/botshield/confirm` handler reads the user from its own session and calls `POST /sdk/confirm-link`. It never takes the account from the request body.

Use `account.link_pending` to know that a link is waiting, for example to confirm it when the person next signs in, before `expires_at`. The webhook carries no account, so it cannot tell you which user to send by itself.

## `POST /sdk/confirm-link`

Call it from your server only, with `Authorization: Bearer <secret API key>`. A site key (`pk_…`) or an agent key is refused with `secret_key_required`.

| Body field | Required | Description |
| - | - | - |
| `request_id` | Yes | The request the person tapped, `req_…`. It is on `account.link_pending`. |
| `partner_user_ref` | Yes | The user ID your own session shows for the signed-in person. The same kind of value you pass as `platform-user-ref`. `partner_user_id` is accepted as another name for it. |

```bash curl theme={null}
curl -s https://api.botshield.ai/operations/sdk/confirm-link \
  -H "Authorization: Bearer $BOTSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "req_4b1f0c6e2a9d4e7f8a3b5c6d7e8f9a0b", "partner_user_ref": "usr_8f31c2d9"}'
```

```typescript SDK theme={null}
import { BotShield } from "botshield-sdk";

const botshield = new BotShield({ serverURL: "https://api.botshield.ai/operations" });
const key = { apiKeyAuth: `Bearer ${process.env.BOTSHIELD_API_KEY}` };

// In your signed-in handler: the account comes from YOUR session, never the request body.
const res = await botshield.census.confirmLink(key, {
  requestId: req.body.request_id,
  partnerUserRef: req.session.user.id,
});
if (res.data.error) throw new Error(res.data.error.code);

await db.users.update(req.session.user.id, { botshieldHandle: res.data.data?.handle });
```

```json theme={null}
{
  "data": {
    "data": {
      "linked": true,
      "state": "live",
      "first_time": true,
      "request_id": "req_4b1f0c6e2a9d4e7f8a3b5c6d7e8f9a0b",
      "handle": "OP_QDhs65484684",
      "trusted": true,
      "trusted_since": "2026-11-18T17:04:05.000Z",
      "verification_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6..."
    }
  }
}
```

| Field | Description |
| - | - |
| `linked`, `state` | `true` and `live`. |
| `first_time` | `true` on the confirm that made the link live. `false` when you confirm a live link again. |
| `handle` | The account's opaque handle, `OP_` followed by 12 characters. Store it beside your user. |
| `trusted`, `trusted_since` | `true`, and when the account became BotShield Verified. |
| `verification_token` | The finished token, an ES256 JWT. It is given only on this response, lives 2 minutes and is good for one check. |

The confirm is safe to repeat. Confirming a live link again with the same account answers `linked: true` with `first_time: false` and a new token, and sends no second webhook.

The SDK method is `census.confirmLink` in `botshield-sdk` 4.0.1 and later.

### Errors

Errors arrive as `data.error` with HTTP 200, like every BotShield operation. Nothing becomes BotShield Verified on any error.

| `statusCode` | `code` | Cause |
| - | - | - |
| 401 | `secret_key_required` | No key, or a key that is not your secret API key. |
| 401 | `invalid_key` | The key is invalid, expired or revoked. |
| 400 | `account_required` | `partner_user_ref` is missing. |
| 404 | `link_not_found` | No link with this `request_id` is waiting for your organization. A request of another organization reads the same. |
| 403 | `environment_mismatch` | The link was started in the other environment. Confirm it with a key from the same environment. |
| 403 | `link_account_mismatch` | The account you sent is not the one the link was started for. The waiting link is dropped. |
| 410 | `link_expired` | More than 24 hours passed since the tap. Start a new link. |
| 409 | `link_refused` | This link was already refused. Start a new link. |
| 409 | `already_trusted` | The person is at the number of accounts you allow. `reason_name` is `account_limit_reached`. See [Account limits](https://docs.botshield.ai/verified-accounts/lifecycle.md#account-limits). |
| 409 | `rebind_requires_prior_id` | The account is already verified with another BotShield ID. |
| 503 | `unavailable` | BotShield is unavailable right now. Try the confirm again. |

> [!WARNING]
>
> `link_account_mismatch` means the person who tapped was looking at a different account from the one your session shows. Do not retry with the account from the link. Send only what your own session says.

## Confirm in the token check instead

If you already send every token to `POST /sdk/verify-token`, you can confirm there. With your secret API key, add `partner_user_ref` to the check. When the token's link is pending, the check confirms it and answers with a `link` object:

```json theme={null}
{
  "data": {
    "data": {
      "valid": true,
      "claims": {
        "request_id": "req_4b1f0c6e2a9d4e7f8a3b5c6d7e8f9a0b",
        "trusted": true,
        "trusted_since": "2026-11-18T17:04:05.000Z",
        "link_state": "live"
      },
      "link": { "state": "live", "confirmed": true, "handle": "OP_QDhs65484684", "first_time": true }
    }
  }
}
```

| `link.state` | Meaning |
| - | - |
| `live` | Confirmed. `confirmed: true`, with the `handle` and `first_time`. |
| `pending` | You did not send `partner_user_ref`. `code` is `link_pending`. The link still waits. |
| `not_live` | The confirm was refused. `code` and `message` are one of the errors above. |

A token for a link that is not pending carries no `link` object.

## What reads as BotShield Verified while a link waits

A pending link counts for nothing until your server confirms it.

| Where | While pending | After the confirm |
| - | - | - |
| Token claim `trusted` | `false`, with `link_state: "pending"` | `true` |
| `GET /verification/status` | `link_state: "pending"`, `link_expires_at`, `link_code: "link_pending"` | `link_state: "live"` |
| `GET /secured-accounts/status` | `none` | `fresh` or `stale` |
| Webhooks | `account.link_pending`, and `gate.human_verified` with `trusted: false` and no `handle` | `account.link_live` and `account.secured` |
| Console registry | **Waiting** | **Linked** |
| The person's BotShield app | Not in their Verified list | In the list |

A pending link never blocks the account's real owner. If someone else's link for the account is waiting, the owner can still verify it.

## Try it in Development

In the Console, open **Verified Accounts**, then **Try it**, and verify your own account with your Development key. The link reads **Waiting** until it is confirmed. In Development, **Confirm as my server** stands in for your server and runs the same confirm. In Production, only your server can confirm.

## Next steps

> [card] [Token and webhooks](https://docs.botshield.ai/verified-accounts/token-and-webhooks.md)
>
> `account.link_pending`, `account.link_live` and the token claims.

> [card] [Account lifecycle](https://docs.botshield.ai/verified-accounts/lifecycle.md)
>
> Pending, live, paused and ended.


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