Quantum Art Auth API

openapi: 3.1.0
info:
  title: QaaS Backend admin Auth API
  description: Quantum-as-a-Service Backend providing task management, metrics, and real-time communication
  version: 1.0.0
tags:
- name: Auth
paths:
  /auth/login:
    post:
      summary: Login
      description: 'Phase 1 of login: validate the password, then either issue tokens

        (bypass accounts / MFA disabled) or start an email MFA challenge.


        When a challenge is started this returns ``{mfa_required: true, mfa_token}``

        and emails a one-time code; the client completes the flow via

        ``POST /auth/login/verify-mfa``.'
      operationId: login_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Credentials
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/login/verify-mfa:
    post:
      summary: Verify Mfa
      description: 'Phase 2 of login: verify the emailed code and issue JWT tokens.'
      operationId: verify_mfa_auth_login_verify_mfa_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/login/resend-mfa:
    post:
      summary: Resend Mfa
      description: Re-send a fresh verification code for an in-flight MFA session.
      operationId: resend_mfa_auth_login_resend_mfa_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/register:
    post:
      tags:
      - Auth
      summary: Register
      description: "Public registration endpoint — creates a pending registration request.\n\nBody shape (form v2)::\n\n    {\n        \"first_name\":     str,                      # required\n        \"last_name\":      str,                      # required\n        \"email\":          str,                      # required\n        \"organization\":   str,                      # required\n        \"form_answers\": {\n            \"heard_from\":            str,           # required\n            \"interest\":              str,           # required\n            \"country_of_residency\":  str,           # required\n            \"additional_info\":       str | null,    # optional\n            \"keep_updated\":          bool            # optional marketing opt-in\n        },\n        \"legal_accepted\": bool,                     # must be true\n        \"recaptcha_token\": str | null               # reCAPTCHA v2 token\n    }\n\nNo credentials are collected: the activation pipeline mints them\nafter an admin confirms the request and the user completes\nactivation. See migration_2026_05_registration_v2.sql.\n\nThe `recaptcha_token` is the \"I'm not a robot\" response from the\npublic form. It is verified here (a no-op unless RECAPTCHA_SECRET_KEY\nis configured) and never persisted — `submit_request` ignores unknown\ntop-level keys."
      operationId: register_auth_register_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Registration Data
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/verify-email/{token}:
    get:
      tags:
      - Auth
      summary: Verify Email
      description: 'Flip a pending request to ''verified'' via the email link.


        Returns a friendly HTML page rather than a JSON body — this URL is

        clicked from a mail client, not consumed by JavaScript. The HTTP

        status is 200 on success or 400 on a failure case (invalid /

        expired) so any monitoring still sees the right signal.'
      operationId: verify_email_auth_verify_email__token__get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer