openapi: 3.0.3
info:
  title: QwikLive Onboarding API
  version: "1.0.0"
  description: >
    Administrative onboarding and configuration API for the QwikLive platform.
    Covers authentication, MFA/OTP, RBAC (users, roles, modules), financial-institution
    onboarding, core connectivity, account types, transaction capabilities, terminal
    keys, transactions, sub-tenants, dashboard statistics and service health.

    Derived from the source Postman collection. All examples use synthetic/masked data.
    Values, types or business rules not present in the source are marked "To be confirmed".
  contact:
    name: QwikLive Platform Team
  license:
    name: Proprietary

servers:
  - url: https://{host}/v1
    description: Environment base (host to be confirmed)
    variables:
      host:
        default: dev.api.qwiklive.io
  - url: http://localhost:9000/v1
    description: Local development (observed)

tags:
  - { name: Authentication, description: Login, logout, token refresh, session and SSO. }
  - { name: MFA, description: Multi-factor authentication (TOTP). }
  - { name: OTP, description: Email one-time passwords. }
  - { name: Users, description: User management. }
  - { name: Roles, description: Role definitions (RBAC). }
  - { name: Modules, description: Module / action catalog. }
  - { name: Financial Institutions, description: Onboard and manage FIs. }
  - { name: Account Types, description: Standardized account types. }
  - { name: Transaction Capabilities, description: Allowed transactions per FI/account type. }
  - { name: Core Connectivity, description: Core banking connection configuration. }
  - { name: App Properties, description: Environment-scoped configuration. }
  - { name: Terminal Keys, description: Terminal/app key registration. }
  - { name: Transactions, description: Query and export transactions. }
  - { name: Sub-tenants, description: Sub-tenant onboarding. }
  - { name: Dashboard, description: BizOps statistics. }
  - { name: Error Codes, description: Error-code catalog. }
  - { name: Service Health, description: Aggregated microservice health. }

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    correlationId:
      name: x-correlation-id
      in: header
      required: false
      description: Client-generated UUID echoed in responses/logs for tracing.
      schema: { type: string, format: uuid }
    page:
      name: page
      in: query
      required: false
      schema: { type: integer, default: 1 }
    size:
      name: size
      in: query
      required: false
      schema: { type: integer, default: 10 }
    isActive:
      name: isActive
      in: query
      required: true
      schema: { type: boolean }
  schemas:
    Envelope:
      type: object
      properties:
        data: {}
        success: { type: boolean, example: true }
        message: { type: string, example: Success }
        timestamp: { type: string, format: date-time }
    Error:
      type: object
      properties:
        data: { nullable: true }
        success: { type: boolean, example: false }
        message: { type: string, example: "Validation failed" }
        timestamp: { type: string, format: date-time }
  responses:
    Success:
      description: Successful response (standard envelope)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Envelope' }
    BadRequest:
      description: Bad Request — invalid or missing fields
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
    Unauthorized:
      description: Unauthorized — missing/expired/invalid token
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
    NotFound:
      description: Not Found
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
    ServerError:
      description: Internal Server Error
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

paths:
  # ----------------------------- Authentication -----------------------------
  /onboarding/login/user:
    post:
      tags: [Authentication]
      summary: Log in and obtain an access token
      description: >-
        Authenticates a user and returns a JWT access token plus profile and
        module entitlements. The `email` and `password` fields are transmitted
        as encrypted strings.
      security: []
      parameters: [ { $ref: '#/components/parameters/correlationId' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, example: "<ENCRYPTED_EMAIL>" }
                password: { type: string, example: "<ENCRYPTED_PASSWORD>" }
            example: |
              {
                "email": "<ENCRYPTED_EMAIL>",
                "password": "<ENCRYPTED_PASSWORD>"
              }
      responses:
        '200':
          description: Authenticated.
          content:
            application/json:
              example: |
                {
                  "data": "<JWT_TOKEN>",
                  "success": true,
                  "message": "Login successful",
                  "timestamp": "2026-06-03T10:15:30.000Z"
                }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /onboarding/logout:
    post:
      tags: [Authentication]
      summary: Log out the current session
      description: Invalidates the current session/token.
      parameters: [ { $ref: '#/components/parameters/correlationId' } ]
      responses:
        '200':
          description: Logged out.
          content:
            application/json:
              example: |
                {
                  "success": true,
                  "message": "Logout successful",
                  "timestamp": "2026-06-03T10:20:00.000Z"
                }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /onboarding/auth/refresh:
    post:
      tags: [Authentication]
      summary: Refresh the access token
      description: Issues a new access token from a valid refresh token / session cookie.
      security: []
      responses:
        '200':
          description: New token issued.
          content:
            application/json:
              example: |
                {
                  "data": "<NEW_JWT_TOKEN>",
                  "success": true,
                  "message": "Token refreshed",
                  "timestamp": "2026-06-03T10:25:00.000Z"
                }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /onboarding/me:
    get:
      tags: [Authentication]
      summary: Get the current authenticated user
      description: Returns the profile of the user bound to the supplied token.
      responses:
        '200':
          description: Current user.
          content:
            application/json:
              example: |
                {
                  "data": {
                    "id": "ec7cc8b9-a485-416e-b480-63624a0f2ba1",
                    "userName": "jdoe",
                    "email": "jane.doe@example.com",
                    "role": "ADMIN",
                    "modules": []
                  },
                  "success": true
                }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /onboarding/userinfo:
    get:
      tags: [Authentication]
      summary: Get user info (OIDC-style)
      description: Returns claims for the authenticated principal.
      responses:
        '200':
          description: Claims.
          content:
            application/json:
              example: |
                {
                  "sub": "ec7cc8b9-a485-416e-b480-63624a0f2ba1",
                  "email": "jane.doe@example.com",
                  "role": "ADMIN"
                }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /onboarding/token:
    post:
      tags: [Authentication]
      summary: Exchange an authorization code for a token (SSO)
      description: >-
        OAuth2-style token endpoint used for SSO integrations (e.g. Grafana).
        Body is `application/x-www-form-urlencoded`.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type: { type: string }
                code: { type: string }
                redirect_uri: { type: string }
                client_id: { type: string }
                client_secret: { type: string }
            example: |
              grant_type=authorization_code
              code=<AUTH_CODE>
              redirect_uri=https://app.example.com/login/callback
              client_id=<CLIENT_ID>
              client_secret=<CLIENT_SECRET>
      responses:
        '200':
          description: Token issued.
          content:
            application/json:
              example: |
                {
                  "access_token": "<JWT_TOKEN>",
                  "token_type": "Bearer",
                  "expires_in": 3600
                }

  # ----------------------------- MFA -----------------------------
  /onboarding/login/mfa/status:
    post:
      tags: [MFA]
      summary: Check MFA status for a user
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string, example: "<ENCRYPTED_EMAIL>" }
                password: { type: string, example: "<ENCRYPTED_PASSWORD>" }
      responses:
        '200':
          description: MFA status (envelope not used)
          content:
            application/json:
              examples:
                notRequired: { value: { MFAEnabled: false, MFARegistrationEnabled: false } }
                registration: { value: { encodedSecret: "OZCVGSDDGFFGQ4KFN5YHOQSMGR3WMTDR", qrCode: "<BASE64_PNG>", MFAEnabled: true, MFARegistrationEnabled: true } }

  /onboarding/login/mfa/register:
    post:
      tags: [MFA]
      summary: Register an MFA (TOTP) device
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, encodedSecret, initialCode]
              properties:
                username: { type: string, example: "<ENCRYPTED_USERNAME>" }
                encodedSecret: { type: string, example: "GJSEGMLVONHUMSRUJVLEQT3QJI4FK3ZY" }
                deviceName: { type: string, example: "My Authenticator App" }
                initialCode: { type: string, example: "575851" }
                overwrite: { type: boolean, example: false }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' } }

  # ----------------------------- OTP -----------------------------
  /onboarding/generateOtp:
    post:
      tags: [OTP]
      summary: Generate an OTP
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, required: [mailID], properties: { mailID: { type: string, example: "jane.doe@example.com" } } }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/validateOtp:
    post:
      tags: [OTP]
      summary: Validate an OTP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [mailID, otp]
              properties:
                mailID: { type: string, example: "jane.doe@example.com" }
                otp: { type: string, example: "339261" }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' } }

  # ----------------------------- Users -----------------------------
  /onboarding/users:
    post:
      tags: [Users]
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [firstName, lastName, mailID, roleId]
              properties:
                firstName: { type: string, example: "Jane" }
                lastName: { type: string, example: "Doe" }
                mailID: { type: string, example: "jane.doe@example.com" }
                isActive: { type: boolean, example: true }
                roleId: { type: string, format: uuid, example: "8d03710e-2b79-4e78-9905-44520224d956" }
                roleName: { type: string, example: "admin" }
                mfaEnable: { type: boolean, example: true }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' } }
    patch:
      tags: [Users]
      summary: Update a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string, format: uuid }
                firstName: { type: string }
                lastName: { type: string }
                mailID: { type: string }
                mfaEnable: { type: boolean }
      responses: { '200': { $ref: '#/components/responses/Success' }, '404': { $ref: '#/components/responses/NotFound' } }

  /onboarding/users/list:
    post:
      tags: [Users]
      summary: List users (paged)
      parameters: [ { $ref: '#/components/parameters/page' }, { $ref: '#/components/parameters/size' } ]
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/users/{id}:
    get:
      tags: [Users]
      summary: Get a user by id
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses: { '200': { $ref: '#/components/responses/Success' }, '404': { $ref: '#/components/responses/NotFound' } }

  /onboarding/users/{id}/activation:
    patch:
      tags: [Users]
      summary: Activate / deactivate a user
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/users/password:
    patch:
      tags: [Users]
      summary: Set / reset a user password
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string, example: "<ENCRYPTED_EMAIL>" }
                password: { type: string, example: "<ENCRYPTED_PASSWORD>" }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/verify-invite-url:
    post:
      tags: [Users]
      summary: Verify an invitation link
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, properties: { email: { type: string, example: "<ENCRYPTED_EMAIL>" } } }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Roles -----------------------------
  /onboarding/roles:
    post:
      tags: [Roles]
      summary: Create a role
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [roleName, modules]
              properties:
                roleName: { type: string, example: "Operations" }
                modules:
                  type: array
                  items:
                    type: object
                    properties:
                      moduleId: { type: string }
                      actionId: { type: array, items: { type: string } }
                createdBy: { type: string }
                description: { type: string }
                isEnabled: { type: boolean }
      responses: { '201': { $ref: '#/components/responses/Success' } }
    patch:
      tags: [Roles]
      summary: Update a role
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string, format: uuid }
                roleName: { type: string }
                modules: { type: array, items: { type: object } }
                modifiedBy: { type: string }
                description: { type: string }
                isEnabled: { type: boolean }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/roles/list:
    post:
      tags: [Roles]
      summary: List roles (paged)
      parameters: [ { $ref: '#/components/parameters/page' }, { $ref: '#/components/parameters/size' } ]
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/roles/{id}:
    get:
      tags: [Roles]
      summary: Get a role by id
      security: []
      parameters: [ { name: id, in: path, required: true, schema: { type: string, format: uuid } } ]
      responses: { '200': { $ref: '#/components/responses/Success' }, '404': { $ref: '#/components/responses/NotFound' } }

  /onboarding/roles/role-list:
    get:
      tags: [Roles]
      summary: List role ids and names
      security: []
      parameters:
        - { name: tenantCode, in: query, required: false, schema: { type: string } }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/roles/{id}/activation:
    patch:
      tags: [Roles]
      summary: Activate / deactivate a role
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Modules -----------------------------
  /onboarding/module-data/listModules:
    get:
      tags: [Modules]
      summary: List modules
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/module-data:
    post:
      tags: [Modules]
      summary: Create module data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                moduleType: { type: string, example: "Module Access" }
                createdBy: { type: string }
                modules:
                  type: array
                  items:
                    type: object
                    properties:
                      moduleName: { type: string }
                      subModules:
                        type: array
                        items:
                          type: object
                          properties:
                            subModuleName: { type: string }
                            action: { type: array, items: { type: string } }
      responses: { '201': { $ref: '#/components/responses/Success' } }
    patch:
      tags: [Modules]
      summary: Update module data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string, format: uuid }
                moduleType: { type: string }
                moduleName: { type: string }
                subModuleName: { type: string }
                tabName: { type: string }
                action: { type: string }
                description: { type: string }
                updatedBy: { type: string }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/module-data/list:
    post:
      tags: [Modules]
      summary: List module data
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/module-data/{id}/activation:
    patch:
      tags: [Modules]
      summary: Activate / deactivate module data
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Financial Institutions -----------------------------
  /onboarding/financialInstitution:
    post:
      tags: [Financial Institutions]
      summary: Onboard a financial institution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [financialInstitutionId, name, coreName]
              properties:
                financialInstitutionId: { type: string, example: "000100" }
                bin: { type: string, example: "123456" }
                name: { type: string, example: "Example Bank" }
                coreName: { type: string, example: "summit-2023" }
                apiType: { type: string, example: "REST" }
                apiUrl: { type: string, example: "https://core.example.com/api/v1" }
                isEnabled: { type: boolean }
                defAccTypeId: { type: integer }
                includeUnlinkedAccounts: { type: boolean }
                minAmount: { type: number }
                maxAmount: { type: number }
                transactionType: { type: string, example: "BALANCEINQUIRY,ACCOUNTLOOKUP" }
                qwikliveSapiUrl: { type: string }
      responses: { '201': { $ref: '#/components/responses/Success' } }

  /onboarding/financial-institutions:
    post:
      tags: [Financial Institutions]
      summary: List financial institutions (paged)
      security: []
      parameters: [ { $ref: '#/components/parameters/page' }, { $ref: '#/components/parameters/size' } ]
      responses: { '200': { $ref: '#/components/responses/Success' } }
    patch:
      tags: [Financial Institutions]
      summary: Update a financial institution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: integer, example: 84 }
                financialInstitutionId: { type: string }
                bin: { type: string }
                name: { type: string }
                coreName: { type: string }
                apiType: { type: string }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/financial-institutions/{id}/activation:
    patch:
      tags: [Financial Institutions]
      summary: Activate / deactivate an FI
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/financial-institutions/ids:
    get:
      tags: [Financial Institutions]
      summary: List FI ids
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/financial-institutions/transaction-types/{id}:
    get:
      tags: [Financial Institutions]
      summary: Get transaction types for an FI
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Account Types -----------------------------
  /onboarding/account-types:
    post:
      tags: [Account Types]
      summary: Create account types
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  standarizedAccountType: { type: string, example: "SAVING234" }
                  accountType: { type: string, example: "Personal" }
                  accountSubType: { type: string }
                  accountSubType2: { type: string }
                  description: { type: string }
                  isEnabled: { type: boolean }
                  priority: { type: integer }
      responses: { '201': { $ref: '#/components/responses/Success' } }

  /onboarding/account-types/list:
    post:
      tags: [Account Types]
      summary: List account types (paged)
      parameters: [ { $ref: '#/components/parameters/page' }, { $ref: '#/components/parameters/size' } ]
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/accounts:
    patch:
      tags: [Account Types]
      summary: Update an account type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: integer, example: 103 }
                standarizedAccountType: { type: string }
                accountType: { type: string }
                accountSubType: { type: string }
                accountSubType2: { type: string }
                description: { type: string }
                isEnabled: { type: boolean }
                priority: { type: integer }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/account-types/{id}/activation:
    patch:
      tags: [Account Types]
      summary: Activate / deactivate an account type
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/account-types/descriptions:
    get:
      tags: [Account Types]
      summary: List account-type descriptions
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Transaction Capabilities -----------------------------
  /onboarding/transaction-capabilities:
    post:
      tags: [Transaction Capabilities]
      summary: Create transaction capabilities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  financialInstitutionId: { type: integer, example: 65 }
                  toAccountType: { type: object, additionalProperties: { type: array, items: { type: integer } }, example: { CASHWITHDRAWAL: [32, 34] } }
                  fromAccountType: { type: object, nullable: true }
      responses: { '201': { $ref: '#/components/responses/Success' } }

  /onboarding/transaction-capability:
    patch:
      tags: [Transaction Capabilities]
      summary: Update a transaction capability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: integer, example: 421 }
                financialInstitutionId: { type: integer }
                fromAccountTypeId: { type: integer, nullable: true }
                toAccountTypeId: { type: integer }
                transactionType: { type: string, example: "BALANCEINQUIRY" }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/transaction-capabilities/{fiId}:
    get:
      tags: [Transaction Capabilities]
      summary: Get capabilities by FI id
      parameters: [ { name: fiId, in: path, required: true, schema: { type: integer } } ]
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/transaction-capabilities/list:
    post:
      tags: [Transaction Capabilities]
      summary: List capabilities (paged, searchable)
      parameters: [ { $ref: '#/components/parameters/page' }, { $ref: '#/components/parameters/size' } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                search: { type: string }
                columnName: { type: array, items: { type: string } }
                sort: { type: string, enum: [asc, desc] }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/transaction-capability/{id}/activation:
    patch:
      tags: [Transaction Capabilities]
      summary: Activate / deactivate a capability
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Core Connectivity -----------------------------
  /onboarding/core-connectivity/data:
    post:
      tags: [Core Connectivity]
      summary: Add core connectivity data
      parameters: [ { $ref: '#/components/parameters/correlationId' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                financialInstitutionId: { type: string }
                coreName: { type: string }
                host: { type: string }
                port: { type: string }
                basepath: { type: string }
                processorUser: { type: string }
                deviceType: { type: string }
                userName: { type: string, description: "Sensitive credential." }
                password: { type: string, description: "Sensitive credential." }
                adminPassword: { type: string, description: "Sensitive credential." }
                findbyServicePath: { type: string }
                accountServicePath: { type: string }
                transactionServicePath: { type: string }
                activeFlag: { type: boolean }
                createdBy: { type: string }
      responses: { '201': { $ref: '#/components/responses/Success' } }

  /onboarding/core-connectivity/data/list:
    post:
      tags: [Core Connectivity]
      summary: List core connectivity data (paged)
      parameters: [ { $ref: '#/components/parameters/page' }, { $ref: '#/components/parameters/size' } ]
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/core-connectivity:
    patch:
      tags: [Core Connectivity]
      summary: Update core connectivity data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: integer }
                financialInstitutionId: { type: string }
                coreName: { type: string }
                host: { type: string }
                port: { type: string }
                basepath: { type: string }
                modifiedBy: { type: string }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/core-connectivity/{id}/activation:
    patch:
      tags: [Core Connectivity]
      summary: Activate / deactivate core connectivity
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- App Properties -----------------------------
  /onboarding/app-properties:
    post:
      tags: [App Properties]
      summary: Add an application property
      parameters: [ { $ref: '#/components/parameters/correlationId' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                appName: { type: string }
                env: { type: string, example: "DEV" }
                propKey: { type: string }
                propVal: { type: string }
                createdBy: { type: string }
                isEnabled: { type: boolean }
      responses: { '201': { $ref: '#/components/responses/Success' } }
    patch:
      tags: [App Properties]
      summary: Update an application property
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: integer }
                appName: { type: string }
                modifiedBy: { type: string }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/app-properties/list:
    post:
      tags: [App Properties]
      summary: List application properties
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/app-properties/{id}/activation:
    patch:
      tags: [App Properties]
      summary: Activate / deactivate a property
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Terminal Keys (rooted at /v1/terminal-key) -----------------------------
  /terminal-key:
    post:
      tags: [Terminal Keys]
      summary: Register a terminal key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appKey, terminalId, financialInstitutionId]
              properties:
                appKey: { type: string, description: "Sensitive." }
                terminalId: { type: string }
                financialInstitutionId: { type: string }
      responses: { '201': { $ref: '#/components/responses/Success' } }
    patch:
      tags: [Terminal Keys]
      summary: Update a terminal key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                appKey: { type: string }
                terminalId: { type: string }
                financialInstitutionId: { type: integer }
                isEnable: { type: boolean }
      responses: { '200': { $ref: '#/components/responses/Success' } }
    get:
      tags: [Terminal Keys]
      summary: Get a single terminal key
      parameters:
        - { name: terminalId, in: query, required: true, schema: { type: string } }
        - { name: financialInstitutionId, in: query, required: true, schema: { type: string } }
      responses: { '200': { $ref: '#/components/responses/Success' }, '404': { $ref: '#/components/responses/NotFound' } }

  /terminal-key/get-all:
    post:
      tags: [Terminal Keys]
      summary: List terminal keys (paged, searchable)
      parameters: [ { $ref: '#/components/parameters/page' }, { $ref: '#/components/parameters/size' } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                search: { type: string }
                columnName: { type: array, items: { type: string } }
                sort: { type: string }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /terminal-key/activation:
    patch:
      tags: [Terminal Keys]
      summary: Activate / deactivate a terminal key
      parameters:
        - { name: terminalId, in: query, required: true, schema: { type: string } }
        - { name: financialInstitutionId, in: query, required: true, schema: { type: string } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Transactions -----------------------------
  /onboarding/transactions:
    post:
      tags: [Transactions]
      summary: List transactions by date range (paged)
      parameters:
        - { name: fromDate, in: query, required: true, schema: { type: string, format: date-time } }
        - { name: toDate, in: query, required: true, schema: { type: string, format: date-time } }
        - { $ref: '#/components/parameters/page' }
        - { $ref: '#/components/parameters/size' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/transactions/all:
    post:
      tags: [Transactions]
      summary: List all transactions (paged)
      parameters: [ { $ref: '#/components/parameters/page' }, { $ref: '#/components/parameters/size' } ]
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/transaction/export:
    post:
      tags: [Transactions]
      summary: Export transactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from: { type: string }
                selectedColumns: { type: array, items: { type: string }, example: ["acquirerid", "transaction_type"] }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Sub-tenants -----------------------------
  /onboarding/sub-tenants/list:
    post:
      tags: [Sub-tenants]
      summary: List sub-tenants
      parameters: [ { $ref: '#/components/parameters/correlationId' } ]
      responses: { '200': { $ref: '#/components/responses/Success' } }

  /onboarding/sub-tenants:
    post:
      tags: [Sub-tenants]
      summary: Add a sub-tenant (multipart)
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                enterpriseTenantCode: { type: string, example: "EDGEONE" }
                subTentContactEmail: { type: string, example: "contact@example.com" }
                subTenantName: { type: string, example: "Symitar" }
                tenantFiId: { type: string, example: "90001" }
                isEnabled: { type: boolean }
                displayName: { type: string }
                logo: { type: string, format: binary }
      responses: { '201': { $ref: '#/components/responses/Success' } }

  /onboarding/sub-tenants/{tenantCode}/activation:
    patch:
      tags: [Sub-tenants]
      summary: Activate / deactivate a sub-tenant
      parameters:
        - { name: tenantCode, in: path, required: true, schema: { type: string } }
        - { $ref: '#/components/parameters/isActive' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Dashboard -----------------------------
  /onboarding/bizops-dashboard/statistics:
    post:
      tags: [Dashboard]
      summary: Get BizOps dashboard statistics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: All blocks optional; supply only the slices you need.
              properties:
                transactionStatus: { type: object }
                transactionByYear: { type: object }
                transactionByCore: { type: object }
                transactionByTerminal: { type: object }
                transactionByFinancialInstitution: { type: object }
                transactionByTransactionType: { type: object }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Error Codes -----------------------------
  /onboarding/error-codes/list:
    post:
      tags: [Error Codes]
      summary: List error codes (paged)
      parameters:
        - { $ref: '#/components/parameters/correlationId' }
        - { $ref: '#/components/parameters/page' }
        - { $ref: '#/components/parameters/size' }
      responses: { '200': { $ref: '#/components/responses/Success' } }

  # ----------------------------- Service Health -----------------------------
  /onboarding/healthstatus:
    post:
      tags: [Service Health]
      summary: Get aggregated microservice health
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fetchAllMicroServiceHealth: { type: boolean }
                services: { type: array, items: { type: string } }
      responses: { '200': { $ref: '#/components/responses/Success' } }