ClawLink Registration API

openapi: 3.2.0
info:
  title: ClawLink Agent Registration API
  version: 1.0.0
  summary: Tool discovery and execution for AI agents
  description: 'ClawLink connects AI agents to 100+ external apps (Gmail, Slack, Notion, GitHub, and more) through one hosted account. This document describes the agent-facing surface: tool discovery, tool execution, the MCP endpoint, and the two credential registration flows. How authentication works, including the human-approval requirement, is documented at https://claw-link.dev/auth.md. All other routes on claw-link.dev (dashboard, billing, connect pages) are browser-facing and not part of this API.'
  contact:
    name: ClawLink
    url: https://claw-link.dev
servers:
- url: https://claw-link.dev
security:
- ApiKeyHeader: []
- BearerAuth: []
tags:
- name: Registration
  description: Obtain a cllk_live_ API key. Every flow requires a signed-in human to approve in a browser. Do not probe these endpoints during passive scans; they create sessions and mint credentials.
paths:
  /api/openclaw/pair/start:
    post:
      tags:
      - Registration
      operationId: startPairing
      summary: Start a pairing session
      description: 'Starts the pairing flow used by the OpenClaw plugin and the CLI. The response includes a pairUrl for the human to open while signed in, and a verifier that must stay on the calling machine: it is the proof that lets this process, and no one else, claim the minted key.'
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                deviceLabel:
                  type: string
                  description: Human-readable device name shown on the approval page and in the dashboard.
                client:
                  type: string
                  description: Set to "cli" for CLI installs; omit for the OpenClaw plugin.
      responses:
        '200':
          description: Pairing session created
          content:
            application/json:
              schema:
                type: object
                required:
                - sessionToken
                - pairUrl
                - verifier
                - expiresAt
                properties:
                  sessionToken:
                    type: string
                  displayCode:
                    type: string
                    description: Short code shown to the user to match device and browser.
                  deviceLabel:
                    type:
                    - string
                    - 'null'
                  status:
                    type: string
                  expiresAt:
                    type: string
                  pollIntervalMs:
                    type: integer
                  pairUrl:
                    type: string
                    description: Approval URL (https://claw-link.dev/openclaw/pair/<token>). Show it to the user; they approve while signed in.
                  verifier:
                    type: string
                    description: Keep secret on the calling machine. Required by the exchange call.
        default:
          description: Session could not be created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/openclaw/pair/sessions/{token}/exchange:
    post:
      tags:
      - Registration
      operationId: exchangePairing
      summary: Exchange an approved pairing session for an API key
      description: After the human approves the pairUrl, present the verifier from startPairing to receive the cllk_live_ key. The session token alone is not sufficient. Store the key locally; the server keeps only its SHA-256 hash and cannot show it again.
      security: []
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
        description: sessionToken from startPairing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - verifier
              properties:
                verifier:
                  type: string
      responses:
        '200':
          description: API key issued
          content:
            application/json:
              schema:
                type: object
                required:
                - apiKey
                properties:
                  session:
                    type: object
                    additionalProperties: true
                  apiKey:
                    type: string
                    description: The cllk_live_ key. This is the only time it is transmitted.
                  apiKeyId:
                    type:
                    - integer
                    - string
        '400':
          $ref: '#/components/responses/BadRequest'
        default:
          description: Session invalid, expired, or not yet approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/hermes/bootstrap-sessions:
    post:
      tags:
      - Registration
      operationId: createBootstrapSession
      summary: Start a Hermes bootstrap session
      description: Registration flow used by the Hermes plugin installer. The human opens approval_url while signed in; the installer polls poll_url and receives the install config, containing the key, after approval. Sessions expire after 15 minutes.
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Bootstrap session created
          content:
            application/json:
              schema:
                type: object
                required:
                - session_id
                - approval_url
                - poll_url
                - expires_at
                properties:
                  session_id:
                    type: string
                  status:
                    type: string
                  approval_url:
                    type: string
                  poll_url:
                    type: string
                  expires_at:
                    type: string
                  poll_interval_ms:
                    type: integer
                  display:
                    type: object
                    properties:
                      title:
                        type: string
                      summary:
                        type: string
        default:
          description: Session could not be created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-clawlink-api-key
      description: A cllk_live_ API key obtained through one of the registration flows.
    BearerAuth:
      type: http
      scheme: bearer
      description: The same cllk_live_ key as a bearer token. Both header forms are accepted on every authenticated endpoint.
    OAuth2:
      type: oauth2
      description: For remote MCP clients calling /api/mcp. Discovery starts at https://claw-link.dev/.well-known/oauth-protected-resource; client registration follows the authorization server metadata.
      flows:
        authorizationCode:
          authorizationUrl: https://clerk.claw-link.dev/oauth/authorize
          tokenUrl: https://clerk.claw-link.dev/oauth/token
          refreshUrl: https://clerk.claw-link.dev/oauth/token
          scopes:
            openid: Identify the authorizing user
            email: Read the user's email address
            profile: Read basic profile information
externalDocs:
  description: ClawLink documentation
  url: https://docs.claw-link.dev