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

# Create a one-time claim link for an API key

> Mint a one-time claim link that carries ``api_key`` to another device (the QR
onboarding leg). The submitted key is resolved through the gate's own verifier chain
and the caller must own it (or be admin) per the module's ownership rule; the response
returns the claim token ONCE plus a fragment-carrier path (``/login#claim=<token>``)
and an expiry.

Accepted oracle (deliberate, not an oversight): an unresolvable key answers 400 and a
valid-but-not-yours key answers 403, so an authenticated caller can tell a live key
from garbage. This adds NO capability the ``/api/auth/me`` carve-out does not already
grant a caller holding a candidate key. The uniform-404 no-oracle rule governs the
unauthenticated EXCHANGE surface, never this authed creation.



## OpenAPI

````yaml /openapi.json post /api/auth/claim-links
openapi: 3.1.0
info:
  description: The operator HTTP surface served under /api/*.
  title: tai42-skeleton API
  version: 0.1.1
servers: []
security: []
paths:
  /api/auth/claim-links:
    post:
      tags:
        - access-control
      summary: Create a one-time claim link for an API key
      description: >-
        Mint a one-time claim link that carries ``api_key`` to another device
        (the QR

        onboarding leg). The submitted key is resolved through the gate's own
        verifier chain

        and the caller must own it (or be admin) per the module's ownership
        rule; the response

        returns the claim token ONCE plus a fragment-carrier path
        (``/login#claim=<token>``)

        and an expiry.


        Accepted oracle (deliberate, not an oversight): an unresolvable key
        answers 400 and a

        valid-but-not-yours key answers 403, so an authenticated caller can tell
        a live key

        from garbage. This adds NO capability the ``/api/auth/me`` carve-out
        does not already

        grant a caller holding a candidate key. The uniform-404 no-oracle rule
        governs the

        unauthenticated EXCHANGE surface, never this authed creation.
      operationId: post_api_auth_claim_links
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimLinkCreate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data: {}
                required:
                  - data
                type: object
          description: Success.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Malformed request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Missing or invalid api key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ClaimLinkCreate:
      description: >-
        Create a one-time claim link for an existing API key. The ``api_key`` is
        a raw

        key the caller holds; ``ttl_seconds`` overrides the default lifetime
        (capped at the

        settings ceiling).
      properties:
        api_key:
          minLength: 1
          title: Api Key
          type: string
        ttl_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          title: Ttl Seconds
      required:
        - api_key
      title: ClaimLinkCreate
      type: object
    Error:
      properties:
        error:
          type: string
      required:
        - error
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````