openapi: 3.1.0
info:
  title: HEVN 2FA API
  description: Backend API for HEVN mobile neobank
  version: 0.1.2
servers:
- url: https://api.hevn.finance
  description: Production
tags:
- name: 2FA
paths:
  /api/v1/user/2fa/status:
    get:
      tags:
      - 2FA
      summary: Get Totp Status
      description: Check if 2FA is enabled for the current user.
      operationId: get_totp_status_api_v1_user_2fa_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotpStatusResponse'
      security:
      - HTTPBearer: []
  /api/v1/user/2fa/setup:
    post:
      tags:
      - 2FA
      summary: Setup Totp
      description: Generate TOTP secret and provisioning URI for QR code.
      operationId: setup_totp_api_v1_user_2fa_setup_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotpSetupResponse'
      security:
      - HTTPBearer: []
  /api/v1/user/2fa/activate:
    post:
      tags:
      - 2FA
      summary: Activate Totp
      description: Verify first TOTP code and activate 2FA. Returns recovery codes.
      operationId: activate_totp_api_v1_user_2fa_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotpVerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotpActivateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/user/2fa:
    delete:
      tags:
      - 2FA
      summary: Disable Totp
      description: Disable 2FA. Requires current TOTP code.
      operationId: disable_totp_api_v1_user_2fa_delete
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotpDisableRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Disable Totp Api V1 User 2Fa Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/user/2fa/recovery-codes:
    post:
      tags:
      - 2FA
      summary: Regenerate Recovery Codes
      description: Regenerate recovery codes. Requires current TOTP code.
      operationId: regenerate_recovery_codes_api_v1_user_2fa_recovery_codes_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotpVerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotpActivateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/auth/user/2fa/status:
    get:
      tags:
      - 2FA
      summary: Get Totp Status Package Alias
      description: Check if 2FA is enabled for the current user.
      operationId: get_totp_status_package_alias_api_v1_auth_user_2fa_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotpStatusResponse'
      security:
      - HTTPBearer: []
  /api/v1/auth/user/2fa/setup:
    post:
      tags:
      - 2FA
      summary: Setup Totp Package Alias
      description: Generate TOTP secret and provisioning URI for QR code.
      operationId: setup_totp_package_alias_api_v1_auth_user_2fa_setup_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotpSetupResponse'
      security:
      - HTTPBearer: []
  /api/v1/auth/user/2fa/activate:
    post:
      tags:
      - 2FA
      summary: Activate Totp Package Alias
      description: Verify first TOTP code and activate 2FA. Returns recovery codes.
      operationId: activate_totp_package_alias_api_v1_auth_user_2fa_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotpVerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotpActivateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/auth/user/2fa:
    delete:
      tags:
      - 2FA
      summary: Disable Totp Package Alias
      description: Disable 2FA. Requires current TOTP code.
      operationId: disable_totp_package_alias_api_v1_auth_user_2fa_delete
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotpDisableRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Disable Totp Package Alias Api V1 Auth User 2Fa Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/auth/user/2fa/recovery-codes:
    post:
      tags:
      - 2FA
      summary: Regenerate Recovery Codes Package Alias
      description: Regenerate recovery codes. Requires current TOTP code.
      operationId: regenerate_recovery_codes_package_alias_api_v1_auth_user_2fa_recovery_codes_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotpVerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotpActivateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    TotpStatusResponse:
      properties:
        enabled:
          type: boolean
          title: Enabled
        recoveryCodesRemaining:
          type: integer
          title: Recoverycodesremaining
          default: 0
      type: object
      required:
      - enabled
      title: TotpStatusResponse
      description: Response for 2FA status check.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    TotpActivateResponse:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: true
        recoveryCodes:
          items:
            type: string
          type: array
          title: Recoverycodes
          description: One-time recovery codes. Store these safely.
      type: object
      required:
      - recoveryCodes
      title: TotpActivateResponse
      description: Response after successfully activating 2FA.
    TotpSetupResponse:
      properties:
        secret:
          type: string
          title: Secret
          description: Base32 TOTP secret for manual entry
        provisioningUri:
          type: string
          title: Provisioninguri
          description: otpauth:// URI for QR code
      type: object
      required:
      - secret
      - provisioningUri
      title: TotpSetupResponse
      description: Response when initiating 2FA setup.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TotpDisableRequest:
      properties:
        code:
          type: string
          maxLength: 6
          minLength: 6
          title: Code
          description: Current TOTP code
      type: object
      required:
      - code
      title: TotpDisableRequest
      description: Request to disable 2FA.
    TotpVerifyRequest:
      properties:
        code:
          type: string
          maxLength: 6
          minLength: 6
          title: Code
          description: 6-digit TOTP code
      type: object
      required:
      - code
      title: TotpVerifyRequest
      description: Request to verify a TOTP code.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      x-default: Bearer <token>
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative HEVN API key header. The CLI defaults to Authorization Bearer unless configured with HEVN_API_KEY_HEADER=X-Api-Key.