> ## 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 a link that waits for your server

> Confirms, from your server, a link that is waiting for it. A link waits when the key that started it has **A link waits for my server's confirm** on (Console → Settings → Developer Tools; on by default for keys made since 4.0): the person taps and confirms with their passkey, `account.link_pending` fires, and the link goes live only when your server names the account.

Call with your secret API key and the account your own signed-in session shows. The same account the link was started for makes it live: `account.secured` fires and this response carries the finished token, the only place it is returned. Another account is refused (`link_account_mismatch`) and the waiting link is dropped. A link not confirmed within 24 hours expires (`link_expired`). Confirming a live link again with the same account answers live again, with `first_time: false` and no second webhook.

You can also confirm by sending `partner_user_ref` to `POST /sdk/verify-token` with the waiting token.



## OpenAPI

````yaml /openapi.json post /sdk/confirm-link
openapi: 3.1.0
info:
  title: BotShield API
  version: 2.0.0
  description: >-
    The BotShield partner API.


    **BotShield Gate** — ask whether a live human is present (Human Gate) or
    over an age threshold (Age Gate). The person confirms with their passkey in
    the BotShield app and you receive a signed result. Partners learn *that* a
    user is human, never *who*.


    **Agents Ask** — your agent proposes an action, a verified human confirms or
    denies it, and BotShield signs a Proof of Resolution you can verify offline.


    **Gates API** — place and run gates and BotShield Actions from your server.


    **Verified Accounts** — a person links their account on your platform with a
    passkey; your server reads the status and the registry, and can unlink
    (revoke) an account with its API key.


    Every operation answers HTTP 200 with a `data` envelope; handler errors
    arrive as `data.error`. See the API overview and error reference. In the
    `botshield-sdk` package (2.2.1) these operations live under
    `client.census.*`, `client.verification.*`, `client.gates.*`,
    `client.securedAccounts.*` and `client.actions.*`.
  contact:
    name: BotShield Support
    email: support@botshield.ai
    url: https://botshield.ai
servers:
  - url: https://api.botshield.ai/operations
    description: Production
security: []
tags:
  - name: BotShield Gate
    description: >-
      Ask whether a present human (Human Gate) or a human over an age threshold
      (Age Gate) confirmed, and verify the signed result.
  - name: Gates API
    description: >-
      Place, open, extend and close gates, and place BotShield Actions, from
      your server with an API key that has the `gates:write` scope.
  - name: Verified Accounts
    description: >-
      Confirm a link that waits for your server, and read and end the Verified
      Accounts on your platform, from your server with your secret API key:
      confirm, status, the registry, and revoke (unlink).
  - name: Agents Ask
    description: >-
      Your agent proposes an action; a verified human confirms or denies it in
      the BotShield app; you receive a signed Proof of Resolution.
paths:
  /sdk/confirm-link:
    post:
      tags:
        - BotShield Gate
      summary: Confirm a link that waits for your server
      description: >-
        Confirms, from your server, a link that is waiting for it. A link waits
        when the key that started it has **A link waits for my server's
        confirm** on (Console → Settings → Developer Tools; on by default for
        keys made since 4.0): the person taps and confirms with their passkey,
        `account.link_pending` fires, and the link goes live only when your
        server names the account.


        Call with your secret API key and the account your own signed-in session
        shows. The same account the link was started for makes it live:
        `account.secured` fires and this response carries the finished token,
        the only place it is returned. Another account is refused
        (`link_account_mismatch`) and the waiting link is dropped. A link not
        confirmed within 24 hours expires (`link_expired`). Confirming a live
        link again with the same account answers live again, with `first_time:
        false` and no second webhook.


        You can also confirm by sending `partner_user_ref` to `POST
        /sdk/verify-token` with the waiting token.
      operationId: SdkConfirmLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - request_id
              properties:
                request_id:
                  type: string
                  description: >-
                    The request the person tapped (`req_…`), from
                    `account.link_pending`, `botshield:success` or your own
                    create call.
                partner_user_ref:
                  type: string
                  description: >-
                    The account your own signed-in session shows: the same user
                    ref the link was started with. Hashed, never stored in the
                    clear.
                partner_user_id:
                  type: string
                  description: Alias of partner_user_ref.
      responses:
        '200':
          description: >-
            Result. Errors arrive here (HTTP 200) as `data.error` with `code`,
            `message` and `statusCode`: `secret_key_required` (401),
            `invalid_key` (401), `account_required` (400), `link_not_found` (404
            — no waiting link with this id for your organization),
            `environment_mismatch` (403), `link_account_mismatch` (403 — nothing
            linked, the waiting link is dropped), `link_expired` (410),
            `link_refused` (409), `rebind_requires_prior_id` (409),
            `already_trusted` (409; `reason_name: account_limit_reached` when
            your account limit refused it), `unavailable` (503 — retry).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      data:
                        type: object
                        properties:
                          linked:
                            type: boolean
                          state:
                            type: string
                            enum:
                              - live
                          first_time:
                            type: boolean
                          request_id:
                            type: string
                          handle:
                            type: string
                          trusted:
                            type: boolean
                          trusted_since:
                            type: string
                            format: date-time
                          verification_token:
                            type: string
                            description: The finished token. Single use, 2 minutes.
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                          message:
                            type: string
                          statusCode:
                            type: integer
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret API key (`bs_dev_…` for development, `bs_production_…` for
        production), or a site key (`pk_test_…` / `pk_live_…`) when calling from
        an allowed origin. The Verified Accounts operations take the secret API
        key only and refuse site keys. Create keys in the Console under Settings
        → Developer Tools.

````

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