openapi: 3.1.0
info:
  title: Clawvisor Gateway Auth API
  version: 0.2.0
  description: The Clawvisor gateway API — the authorization layer AI agents call to act on external services (Gmail, Calendar, Drive, Contacts, GitHub, Slack, Notion, Linear, Stripe, Twilio, iMessage) without ever holding the underlying credentials. Agents declare a **task** describing their purpose and the service/action pairs they need; the user approves the scope once; and every subsequent gateway request is checked against restrictions, task scope, intent verification, and (optionally) per-request human approval before Clawvisor injects credentials, executes through an adapter, and returns a clean semantic result. This description is GENERATED by the API Evangelist enrichment pipeline from Clawvisor's public README and agent protocol (skills/clawvisor/SKILL.md.tmpl); Clawvisor does not publish an OpenAPI document. Every path, method, field, and status below is documented in github.com/clawvisor/clawvisor.
  x-generated-by: api-evangelist-enrichment-pipeline
  x-source: https://github.com/clawvisor/clawvisor/blob/main/README.md
  license:
    name: MIT
    url: https://github.com/clawvisor/clawvisor/blob/main/LICENSE
  contact:
    name: Clawvisor
    url: https://clawvisor.com
servers:
- url: https://app.clawvisor.com
  description: Hosted Clawvisor (managed service)
- url: http://localhost:25297
  description: Self-hosted local daemon (default port)
security:
- agentToken: []
tags:
- name: Auth
  description: Local magic-link session exchange.
paths:
  /api/auth/magic:
    post:
      operationId: authMagic
      tags:
      - Auth
      summary: Exchange a magic token for a refresh token
      description: Local-mode session exchange — the TUI reads the one-time magic token written by the server and exchanges it for a refresh token.
      responses:
        '200':
          description: Refresh token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
components:
  schemas:
    Token:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        token:
          type: string
          description: The secret token value (returned only at creation).
        created_at:
          type: string
          format: date-time
  securitySchemes:
    agentToken:
      type: http
      scheme: bearer
      description: Agent token (or dashboard JWT for admin-gated endpoints), sent as Authorization Bearer header.
    agentTokenHeader:
      type: apiKey
      in: header
      name: X-Clawvisor-Agent-Token
      description: Agent token for the skill catalog endpoint.