dialogbrain-com Telegram Auth API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Telegram Auth API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: telegram-auth
paths:
  /api/channels/telegram/auth/qr/start:
    post:
      tags:
      - telegram-auth
      summary: Start Qr Auth
      description: 'Start QR code authentication for Telegram.


        Returns a QR code that users can scan with their Telegram mobile app.


        Returns:

        qr_code_base64: Base64-encoded PNG image of QR code

        token: Token for polling status

        expires_in: Seconds until QR code expires'
      operationId: start_qr_auth_api_channels_telegram_auth_qr_start_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/channels/telegram/auth/qr/status:
    post:
      tags:
      - telegram-auth
      summary: Check Qr Status
      description: 'Check QR code authentication status.


        Poll this endpoint to see if user has scanned the QR code.


        Returns:

        status: "pending", "expired", "success", "needs_2fa", "error"

        On success: session_string, user_info, account_id'
      operationId: check_qr_status_api_channels_telegram_auth_qr_status_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__api__telegram_auth__QRStatusRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/channels/telegram/auth/qr/cancel:
    post:
      tags:
      - telegram-auth
      summary: Cancel Qr Auth
      description: 'Cancel pending QR authentication.


        Args:

        request: Token to cancel


        Returns:

        Success status'
      operationId: cancel_qr_auth_api_channels_telegram_auth_qr_cancel_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__api__telegram_auth__QRStatusRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/channels/telegram/auth/qr/2fa:
    post:
      tags:
      - telegram-auth
      summary: Submit Qr 2Fa
      description: 'Submit 2FA password after QR code scan.


        Args:

        request: Token and 2FA password


        Returns:

        status: "success", "error"

        On success: session_string, user_info, account_id'
      operationId: submit_qr_2fa_api_channels_telegram_auth_qr_2fa_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QR2FARequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/channels/telegram/auth/takeover:
    post:
      tags:
      - telegram-auth
      summary: Takeover Telegram Account
      description: 'Accept the "connect here instead" offer a 409 ``telegram_owned_elsewhere``

        made (QR or phone path). The old login''s connection is switched off and

        the account is created here with the chosen sync scope. Answers the same

        shape as a successful QR status poll.'
      operationId: takeover_telegram_account_api_channels_telegram_auth_takeover_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TakeoverRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/channels/telegram/auth/takeover/cancel:
    post:
      tags:
      - telegram-auth
      summary: Cancel Telegram Takeover
      description: 'Walk away from the offer: the session that was authorised for it is

        logged out so it does not linger on the user''s phone.'
      operationId: cancel_telegram_takeover_api_channels_telegram_auth_takeover_cancel_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TakeoverRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    QR2FARequest:
      properties:
        token:
          type: string
          title: Token
        password:
          type: string
          title: Password
        sync_scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Sync Scope
      type: object
      required:
      - token
      - password
      title: QR2FARequest
      description: Request to submit 2FA password.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    TakeoverRequest:
      properties:
        token:
          type: string
          title: Token
        sync_scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Sync Scope
      type: object
      required:
      - token
      title: TakeoverRequest
      description: Accept (or cancel) a parked "connect here instead" offer.
    src__api__telegram_auth__QRStatusRequest:
      properties:
        token:
          type: string
          title: Token
        sync_scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Sync Scope
      type: object
      required:
      - token
      title: QRStatusRequest
      description: Request to check QR status or cancel auth.