openapi: 3.0.3
info:
  title: HeyForm Auth API
  description: HeyForm is an open-source conversational form builder providing REST and GraphQL endpoints for managing forms, submissions, workspaces, integrations, and webhooks. The primary data API uses GraphQL; this document covers the publicly accessible REST endpoints discovered in the open-source codebase.
  version: 1.0.0
  contact:
    name: HeyForm Support
    url: https://docs.heyform.net
  license:
    name: AGPL-3.0
    url: https://github.com/heyform/heyform/blob/main/LICENSE
servers:
- url: https://api.heyform.net
  description: HeyForm Cloud API
- url: http://localhost:8000
  description: Self-hosted HeyForm instance (default port)
tags:
- name: Auth
  description: Authentication and social login (OAuth)
paths:
  /connect/{kind}:
    get:
      operationId: socialLoginInitiate
      summary: Initiate social login (OAuth)
      description: Redirects the user to the OAuth provider's authorization URL. Supported providers include Google, GitHub, and Apple.
      tags:
      - Auth
      parameters:
      - name: kind
        in: path
        required: true
        description: The OAuth provider identifier (e.g. google, github, apple).
        schema:
          type: string
          enum:
          - google
          - github
          - apple
        example: google
      - name: state
        in: query
        required: true
        description: Browser ID / CSRF state token generated by the client to correlate the callback.
        schema:
          type: string
        example: DMbcJqLJ
      - name: redirect_uri
        in: query
        required: false
        description: Optional URI to redirect to after successful login.
        schema:
          type: string
          format: uri
      responses:
        '302':
          description: Redirect to OAuth provider authorization URL
          headers:
            Location:
              schema:
                type: string
                format: uri
        '200':
          description: Error page rendered in HTML when the state is missing or the provider is unsupported.
          content:
            text/html:
              schema:
                type: string
  /connect/{kind}/callback:
    get:
      operationId: socialLoginCallbackGet
      summary: Handle OAuth callback (GET)
      description: Receives the OAuth authorization code from the provider (GET variant, used by most providers). Validates state, exchanges code for tokens, and logs the user in.
      tags:
      - Auth
      parameters:
      - name: kind
        in: path
        required: true
        description: The OAuth provider identifier.
        schema:
          type: string
          enum:
          - google
          - github
          - apple
        example: google
      - name: code
        in: query
        required: false
        description: Authorization code returned by the OAuth provider.
        schema:
          type: string
      - name: state
        in: query
        required: true
        description: CSRF state token to verify.
        schema:
          type: string
      responses:
        '302':
          description: Redirect to dashboard after successful login
          headers:
            Location:
              schema:
                type: string
        '200':
          description: Error page on failure
          content:
            text/html:
              schema:
                type: string
    post:
      operationId: socialLoginCallbackPost
      summary: Handle OAuth callback (POST)
      description: Receives the OAuth authorization code from the provider via POST (used by Sign in with Apple which posts directly to the backend).
      tags:
      - Auth
      parameters:
      - name: kind
        in: path
        required: true
        description: The OAuth provider identifier.
        schema:
          type: string
          enum:
          - apple
        example: apple
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                code:
                  type: string
                  description: Authorization code from Apple.
                state:
                  type: string
                  description: CSRF state token.
      responses:
        '302':
          description: Redirect to dashboard after successful login
        '200':
          description: Error page on failure
          content:
            text/html:
              schema:
                type: string
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: heyform_sid
      description: Session cookie set by the login mutation or OAuth callback. All authenticated GraphQL mutations and the CSV export endpoint require this cookie.
externalDocs:
  description: HeyForm Documentation
  url: https://docs.heyform.net