dialogbrain-com Auth API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Auth API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: Auth
paths:
  /auth/login:
    post:
      tags:
      - Auth
      summary: Login
      description: 'Login with email and password.


        Returns JWT access token, refresh token, and user information.


        - Access token expires in 15 minutes

        - Refresh token expires in 14 days

        - Implements token rotation for security

        - Rate limited: 10 requests per minute


        Check order: user exists → is_active → email_verified → password

        This allows unverified users to see verification message without correct password.'
      operationId: login_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/LoginResponse'
                - $ref: '#/components/schemas/TwoFARequiredResponse'
                title: Response Login Auth Login Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/me:
    get:
      tags:
      - Auth
      summary: Get Current User
      description: 'Get current authenticated user information.


        Requires valid JWT access token in Authorization header.'
      operationId: get_current_user_auth_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
  /auth/refresh:
    post:
      tags:
      - Auth
      summary: Refresh Token
      description: 'Refresh access token using refresh token.


        Accepts refresh token from:

        1. Request body (preferred - frontend explicitly sends refresh_token)

        2. HTTP-only cookie (secure alternative)

        3. Authorization header (legacy - but NOTE: apiClient sends ACCESS token here!)


        Returns new access token and optionally rotates refresh token.'
      operationId: refresh_token_auth_refresh_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/register:
    post:
      tags:
      - Auth
      summary: Register
      description: 'Register a new user.


        Creates user account with email and password.

        Sends verification email - user must verify before logging in.

        Rate limited: 5 requests per minute.'
      operationId: register_auth_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/verify-email:
    post:
      tags:
      - Auth
      summary: Verify Email
      description: 'Verify user''s email address using 6-digit code from email.


        Accepts email and code in request body.

        Returns access token on success for auto-login.'
      operationId: verify_email_auth_verify_email_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailCodeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/VerifyEmailResponse'
                - $ref: '#/components/schemas/TwoFARequiredResponse'
                title: Response Verify Email Auth Verify Email Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/resend-verification:
    post:
      tags:
      - Auth
      summary: Resend Verification
      description: 'Resend email verification code.

        Rate limited to 60 seconds between requests.

        Returns can_resend_in for frontend countdown timer.'
      operationId: resend_verification_auth_resend_verification_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendVerificationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/email-code/request:
    post:
      tags:
      - Auth
      summary: Email Code Request
      description: 'Passwordless sign-in step 1: email a 6-digit code to the given address.


        If no account exists, one is created on the spot with no password

        (password_hash NULL — same shape as Google OAuth accounts). Existing

        accounts (including password/2FA users) just get a fresh code: email

        possession already equals account access here (2FA codes and password

        resets are both email-based), so this adds no new capability.


        Always returns the same generic success shape — does not reveal whether

        the account already existed. Redeem the code at /auth/email-code/verify.'
      operationId: email_code_request_auth_email_code_request_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailCodeRequestBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailCodeRequestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/email-code/verify:
    post:
      tags:
      - Auth
      summary: Email Code Verify
      description: 'Passwordless sign-in step 2: redeem the 6-digit code for a session.


        Identical semantics to /auth/verify-email (shape gate, attempt cap,

        constant-time compare, expiry check, marks the email verified, auto-login

        token pair) — both call the same body so the two redeem paths can''t drift.'
      operationId: email_code_verify_auth_email_code_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailCodeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/VerifyEmailResponse'
                - $ref: '#/components/schemas/TwoFARequiredResponse'
                title: Response Email Code Verify Auth Email Code Verify Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/forgot-password:
    post:
      tags:
      - Auth
      summary: Forgot Password
      description: Request password reset. Sends email with reset link.
      operationId: forgot_password_auth_forgot_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgotPasswordRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/validate-reset-token:
    get:
      tags:
      - Auth
      summary: Validate Reset Token
      description: Validate password reset token before showing reset form.
      operationId: validate_reset_token_auth_validate_reset_token_get
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          description: Reset token
          title: Token
        description: Reset token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/reset-password:
    post:
      tags:
      - Auth
      summary: Reset Password
      description: Reset password using token from email.
      operationId: reset_password_auth_reset_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/oauth/google:
    get:
      tags:
      - Auth
      summary: Google Oauth Redirect
      description: 'Redirect user to Google OAuth consent screen.

        Uses different OAuth apps based on RU_MARKET_MODE environment variable.


        return_to: optional app-relative path (e.g. /listen/) round-tripped

        SERVER-side through the OAuth state, so flows started in in-app browsers

        (Telegram/WhatsApp webviews hand OAuth to the system browser, losing

        localStorage) still land back where they started — critical for listener

        share links, where losing the path strands the user in onboarding instead

        of joining the workspace.'
      operationId: google_oauth_redirect_auth_oauth_google_get
      parameters:
      - name: return_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Return To
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/oauth/google/callback:
    get:
      tags:
      - Auth
      summary: Google Oauth Callback
      description: 'Handle Google OAuth callback.

        Exchange code for tokens and create/login user.

        Uses different OAuth apps based on RU_MARKET_MODE environment variable.'
      operationId: google_oauth_callback_auth_oauth_google_callback_get
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
          description: Authorization code from Google
          title: Code
        description: Authorization code from Google
      - name: state
        in: query
        required: true
        schema:
          type: string
          description: OAuth state parameter (required, CSRF binding)
          title: State
        description: OAuth state parameter (required, CSRF binding)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/logout:
    post:
      tags:
      - Auth
      summary: Logout
      description: 'Logout: end this session only (see _revoke_session_on_logout). Other

        browsers and the phone stay signed in.'
      operationId: logout_auth_logout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/verify-2fa:
    post:
      tags:
      - Auth
      summary: Verify 2Fa
      description: 'Verify 2FA code and complete login.


        Called after login returns 2fa_required status.

        Returns JWT tokens on successful verification.'
      operationId: verify_2fa_auth_verify_2fa_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Verify2FARequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/resend-2fa:
    post:
      tags:
      - Auth
      summary: Resend 2Fa
      description: 'Resend 2FA verification code.

        Rate limited to 60 seconds between requests.'
      operationId: resend_2fa_auth_resend_2fa_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Resend2FARequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/oauth/apple:
    post:
      tags:
      - Auth
      summary: Login With Apple
      operationId: login_with_apple_auth_oauth_apple_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppleSignInRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/LoginResponse'
                - $ref: '#/components/schemas/TwoFARequiredResponse'
                title: Response Login With Apple Auth Oauth Apple Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/account:
    delete:
      tags:
      - Auth
      summary: Delete My Account
      operationId: delete_my_account_auth_account_delete
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAccountRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/account/deletion-status:
    get:
      tags:
      - Auth
      summary: Account Deletion Status
      description: 'How a deletion started by DELETE /auth/account ended, by its ticket.


        No session: the deletion revoked them all. The ticket (32 hex, returned

        only in the 202) is the proof; an unknown or wrong one is 404.'
      operationId: account_deletion_status_auth_account_deletion_status_get
      parameters:
      - name: ticket
        in: query
        required: true
        schema:
          type: string
          title: Ticket
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    LoginResponse:
      properties:
        accessToken:
          type: string
          title: Accesstoken
        refreshToken:
          type: string
          title: Refreshtoken
        token_type:
          type: string
          title: Token Type
          default: bearer
        expires_in:
          type: integer
          title: Expires In
        user:
          additionalProperties: true
          type: object
          title: User
      type: object
      required:
      - accessToken
      - refreshToken
      - expires_in
      - user
      title: LoginResponse
    AppleSignInRequest:
      properties:
        identity_token:
          type: string
          title: Identity Token
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        nonce:
          anyOf:
          - type: string
          - type: 'null'
          title: Nonce
      type: object
      required:
      - identity_token
      title: AppleSignInRequest
    RegisterResponse:
      properties:
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
        email:
          type: string
          title: Email
        requires_verification:
          type: boolean
          title: Requires Verification
          default: true
      type: object
      required:
      - success
      - message
      - email
      title: RegisterResponse
    RegisterRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
        password:
          type: string
          title: Password
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        referral_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Referral Code
      type: object
      required:
      - email
      - password
      title: RegisterRequest
    EmailCodeRequestResponse:
      properties:
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
        can_resend_in:
          type: integer
          title: Can Resend In
          default: 60
      type: object
      required:
      - success
      - message
      title: EmailCodeRequestResponse
    ResetPasswordRequest:
      properties:
        token:
          type: string
          title: Token
        new_password:
          type: string
          title: New Password
      type: object
      required:
      - token
      - new_password
      title: ResetPasswordRequest
    DeleteAccountRequest:
      properties:
        password:
          anyOf:
          - type: string
          - type: 'null'
          title: Password
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
      type: object
      title: DeleteAccountRequest
    LoginRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
        password:
          type: string
          title: Password
      type: object
      required:
      - email
      - password
      title: LoginRequest
    UserResponse:
      properties:
        id:
          type: string
          title: Id
        email:
          type: string
          title: Email
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        avatarUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatarurl
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        email_verified:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Email Verified
      type: object
      required:
      - id
      - email
      title: UserResponse
    Verify2FARequest:
      properties:
        user_id:
          type: integer
          title: User Id
        code:
          type: string
          title: Code
      type: object
      required:
      - user_id
      - code
      title: Verify2FARequest
    VerifyEmailResponse:
      properties:
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
        accessToken:
          anyOf:
          - type: string
          - type: 'null'
          title: Accesstoken
        refreshToken:
          anyOf:
          - type: string
          - type: 'null'
          title: Refreshtoken
        token_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Token Type
        expires_in:
          anyOf:
          - type: integer
          - type: 'null'
          title: Expires In
        user:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: User
      type: object
      required:
      - success
      - message
      title: VerifyEmailResponse
    EmailCodeRequestBody:
      properties:
        email:
          type: string
          format: email
          title: Email
      type: object
      required:
      - email
      title: EmailCodeRequestBody
    ForgotPasswordRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
      type: object
      required:
      - email
      title: ForgotPasswordRequest
    PasswordResetResponse:
      properties:
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
      type: object
      required:
      - success
      - message
      title: PasswordResetResponse
    TwoFARequiredResponse:
      properties:
        status:
          type: string
          title: Status
          default: 2fa_required
        user_id:
          type: integer
          title: User Id
        email:
          type: string
          title: Email
        message:
          type: string
          title: Message
          default: Verification code sent to email
        expires_in:
          type: integer
          title: Expires In
          default: 300
        method:
          type: string
          title: Method
          default: email
      type: object
      required:
      - user_id
      - email
      title: TwoFARequiredResponse
    ResendVerificationRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
      type: object
      required:
      - email
      title: ResendVerificationRequest
    VerifyEmailCodeRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
        code:
          type: string
          maxLength: 32
          minLength: 1
          title: Code
      type: object
      required:
      - email
      - code
      title: VerifyEmailCodeRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Resend2FARequest:
      properties:
        user_id:
          type: integer
          title: User Id
      type: object
      required:
      - user_id
      title: Resend2FARequest
    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