> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payments.sardine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create KYH Tracking Link

> Creates a short-lived tracking link for the human an AI agent is acting on behalf of. Send the link to the human (for example by SMS or email). When they open it on their own device, Sardine's device SDK collects device and behavior intelligence (DI/BB) under the `sessionKey` you provided, and the page shows the human your `code` (an OTP) to give to the agent.

**How it works**
1. Call this endpoint with a `sessionKey` and a one-time `code` of your own.
2. Deliver the returned `widgetUrl` to the human.
3. The human opens the link on their device. Signals are collected under your `sessionKey`.
4. Call the Sardine Customers or Devices API with the same `sessionKey` to retrieve DI/BB
   signals as you normally would. The link only collects signals; it does not return them.


**Notes**
- The link expires 5 minutes after creation (see `expiresAt`).
- The link can be opened a limited number of times (SMS link scanners may open it first);
  after that it returns `410 Gone`.

- Only one link is active per `sessionKey`. Creating a new link for the same `sessionKey`
  replaces the previous one, which then stops working.

- The `code` is never returned in the API response.




## OpenAPI

````yaml /api_reference/identity.yaml post /identity/kyh/widget
openapi: 3.0.3
info:
  version: '1.0'
  title: Identity API
  description: Reference for Sardine Universal Identity API (identity.sardine.ai)
  contact:
    email: support@sardine.io
    name: Sardine
    url: docs.sardine.io
servers:
  - url: https://api.sandbox.sardine.ai/v1
    description: Sandbox
  - url: https://api.sardine.ai/v1
    description: Production
security:
  - ClientSecret: []
paths:
  /identity/kyh/widget:
    post:
      tags:
        - Know Your Human (KYH)
      summary: Create KYH Tracking Link
      description: >
        Creates a short-lived tracking link for the human an AI agent is acting
        on behalf of. Send the link to the human (for example by SMS or email).
        When they open it on their own device, Sardine's device SDK collects
        device and behavior intelligence (DI/BB) under the `sessionKey` you
        provided, and the page shows the human your `code` (an OTP) to give to
        the agent.


        **How it works**

        1. Call this endpoint with a `sessionKey` and a one-time `code` of your
        own.

        2. Deliver the returned `widgetUrl` to the human.

        3. The human opens the link on their device. Signals are collected under
        your `sessionKey`.

        4. Call the Sardine Customers or Devices API with the same `sessionKey`
        to retrieve DI/BB
           signals as you normally would. The link only collects signals; it does not return them.


        **Notes**

        - The link expires 5 minutes after creation (see `expiresAt`).

        - The link can be opened a limited number of times (SMS link scanners
        may open it first);
          after that it returns `410 Gone`.

        - Only one link is active per `sessionKey`. Creating a new link for the
        same `sessionKey`
          replaces the previous one, which then stops working.

        - The `code` is never returned in the API response.
      operationId: post-identity-kyh-widget
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sessionKey
                - code
              properties:
                sessionKey:
                  type: string
                  maxLength: 255
                  description: >
                    Your session key for this login or signup. Use the same
                    value when you later call the Customers or Devices API to
                    retrieve signals.
                  example: client-session-123
                code:
                  type: string
                  pattern: ^[A-Za-z0-9]{4,12}$
                  description: >
                    The code (OTP) to show the human once they open the link. 4
                    to 12 letters or digits.
                  example: '482913'
            example:
              sessionKey: client-session-123
              code: '482913'
      responses:
        '200':
          description: Tracking link created
          content:
            application/json:
              schema:
                type: object
                properties:
                  widgetUrl:
                    type: string
                    format: uri
                    description: Link to send to the human
                    example: https://identity.sardine.ai/kyh?token=Zk3x9...
                  expiresAt:
                    type: string
                    format: date-time
                    description: When the link expires (UTC, ISO 8601)
                    example: '2026-11-09T18:05:00Z'
              example:
                widgetUrl: https://identity.sardine.ai/kyh?token=Zk3x9...
                expiresAt: '2026-11-09T18:05:00Z'
        '400':
          description: >
            `sessionKey` missing or longer than 255 characters, `code` not 4 to
            12 letters or digits, or `sessionKey` already in use
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid client credentials
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Customer not found for customer ID
        status:
          type: integer
          example: 400
  securitySchemes:
    ClientSecret:
      type: http
      scheme: basic
      description: >
        HTTP Basic Auth. Use your `clientId` as the username and `clientSecret`
        as the password.

````