portal/api/account/swagger.yaml

openapi: 3.0.0
info:
    title: Account Management API
    version: "1.0"
    description: API for managing user accounts, including login, registration, OTP operations, and password resets.
paths:
    /api/auth/login:
        post:
            summary: Login to the system
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/LoginRequest'
            responses:
                '200':
                    description: Successfully logged in
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LoginResponse'
                '401':
                    description: Unauthorized
    /api/auth/logout:
        post:
            summary: Logout of account service
            responses:
                '200':
                    description: Successfully logged out
    /api/auth/register:
        post:
            summary: Register a new account
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/RegisterRequest'
            responses:
                '200':
                    description: Successfully registered
                '400':
                    description: Bad Request
    /api/account/verify-email:
        post:
            summary: Verify email address
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/VerifyEmailRequest'
            responses:
                '200':
                    description: Email verified successfully
    /api/account/verify-email/resend:
        post:
            summary: Resend email verification
            responses:
                '200':
                    description: Email verification resent successfully
    /api/auth/otp/generate:
        get:
            summary: Generate OTP for two-factor authentication
            responses:
                '200':
                    description: OTP generated successfully
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/OTPGenerateResponse'
    /api/account/otp/verify:
        post:
            summary: Verify OTP for enabling two-factor authentication
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/OTPVerifyRequest'
            responses:
                '200':
                    description: OTP verified successfully
    /api/account/otp/validate:
        post:
            summary: Validate OTP for two-factor authentication login
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/OTPValidateRequest'
            responses:
                '200':
                    description: OTP validated successfully
    /api/auth/otp/disable:
        post:
            summary: Disable OTP for two-factor authentication
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/OTPDisableRequest'
            responses:
                '200':
                    description: OTP disabled successfully
    /api/account/password-reset/request:
        post:
            summary: Request a password reset
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PasswordResetRequest'
            responses:
                '200':
                    description: Password reset requested successfully
    /api/account/password-reset/confirm:
        post:
            summary: Confirm a password reset
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PasswordResetVerifyRequest'
            responses:
                '200':
                    description: Password reset successfully
    /api/auth/ping:
        post:
            summary: Auth check endpoint
            responses:
                '200':
                    description: Pong
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PingResponse'
                '401':
                    description: Unauthorized
    /api/account:
        get:
            summary: Get account information
            responses:
                '200':
                    description: Account information retrieved successfully
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AccountInfoResponse'
                '401':
                    description: Unauthorized
    /api/account/update-email:
        post:
            summary: Update email address
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateEmailRequest'
            responses:
                '200':
                    description: Email updated successfully
    /api/account/update-password:
        post:
            summary: Update password
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdatePasswordRequest'
            responses:
                '200':
                    description: Password updated successfully
    /api/upload-limit:
        get:
            summary: Get the basic file upload (POST) upload limit set by the portal
            responses:
                '200':
                    description: Upload limit retrieved successfully
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UploadLimitResponse'
    /api/meta:
        get:
            summary: Get metadata about the portal
            responses:
                '200':
                    description: Metadata retrieved successfully
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MetaResponse'


components:
    schemas:
        LoginRequest:
            type: object
            required:
                - email
                - password
            properties:
                email:
                    type: string
                password:
                    type: string
        LoginResponse:
            type: object
            properties:
                token:
                    type: string
        RegisterRequest:
            type: object
            required:
                - first_name
                - last_name
                - email
                - password
            properties:
                first_name:
                    type: string
                last_name:
                    type: string
                email:
                    type: string
                password:
                    type: string
        VerifyEmailRequest:
            type: object
            required:
                - email
                - token
            properties:
                email:
                    type: string
                token:
                    type: string
        OTPGenerateResponse:
            type: object
            properties:
                OTP:
                    type: string
        OTPVerifyRequest:
            type: object
            required:
                - OTP
            properties:
                OTP:
                    type: string
        OTPValidateRequest:
            type: object
            required:
                - OTP
            properties:
                OTP:
                    type: string
        OTPDisableRequest:
            type: object
            required:
                - password
            properties:
                password:
                    type: string
        PasswordResetRequest:
            type: object
            required:
                - email
            properties:
                email:
                    type: string
        PasswordResetVerifyRequest:
            type: object
            required:
                - email
                - token
                - password
            properties:
                email:
                    type: string
                token:
                    type: string
                password:
                    type: string
        UpdateEmailRequest:
            type: object
            required:
                - email
                - password
            properties:
                email:
                    type: string
                password:
                    type: string
        UpdatePasswordRequest:
            type: object
            required:
                - current_password
                - new_password
            properties:
                current_password:
                    type: string
                new_password:
                    type: string
        PingResponse:
            type: object
            properties:
                ping:
                    type: string
                token:
                    type: string
        AccountInfoResponse:
            type: object
            required:
                - id
                - first_name
                - last_name
                - email
                - verified
            properties:
                id:
                    type: number
                first_name:
                    type: string
                last_name:
                    type: string
                email:
                    type: string
                verified:
                    type: boolean
        UploadLimitResponse:
            type: object
            properties:
                limit:
                    type: number
            required:
                - limit
        MetaResponse:
            type: object
            required:
                - domain
            properties:
                domain:
                    type: string