openapi: 3.0.1
info:
  title: IoT APIs
  description: >-
    IoT APIs for dynamic authentication, device management, and stock
    monitoring. This specification includes detailed summaries and descriptions
    for every operation, parameter, request/response body, and schema so clients
    can integrate without reading code. Examples and field-level constraints
    (formats, patterns, and valid values) are provided wherever applicable.
  contact:
    name: IVALT Support
    url: https://ivalt.com/support
    email: support@ivalt.com
  version: 1.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: IotApis
    description: >-
      Operations related to IoT APIs, including dynamic authentication
      workflows, device lifecycle tasks, and stock price retrieval.
servers:
  - url: https://dev.api.ivalt.com/admin/public/api
    description: Development server.
  - url: https://api.ivalt.com/admin/public/api
    description: Production server.
paths:
  /dynamic_auth/register:
    post:
      summary: Register dynamic authentication
      description: >-
        Create a new dynamic authentication registration for a device. Typically
        called during device onboarding or when associating a device with a
        stock for monitoring. Persists machine metadata, stock details, and
        contact number used for downstream verification and notifications.
      operationId: registerDynamicAuth
      tags:
        - IotApis
      requestBody:
        description: >-
          Machine metadata and stock details for registration. All fields are
          required and validated for format/patterns (see schema for
          constraints).
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterDynamicAuthRequest'
            examples:
              validRequest:
                summary: Valid registration request
                value:
                  machineId: MACHINE-001
                  stockName: ANDROID
                  totalPrice: '200.00'
                  currentStockPrice: '150.00'
                  machineName: Testing-2
                  mobile: '+917837582588'
              anotherValid:
                summary: Another valid request with comma formatting for price strings
                value:
                  machineId: kiosk-44A
                  stockName: TESLA
                  totalPrice: 2,000.00
                  currentStockPrice: 1,850.50
                  machineName: Entrance-Kiosk
                  mobile: '+14155552671'
      responses:
        '200':
          description: >-
            Registration successful. The device and its stock context are now
            recorded and usable in subsequent auth calls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful registration
                  value:
                    status: success
                    message: Device registered successfully
        '400':
          description: >-
            Invalid request payload. One or more required fields are missing or
            failed validation (e.g., patterns, formats).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingField:
                  summary: Missing required machineId
                  value:
                    status: error
                    message: Field 'machineId' is required.
                invalidMobile:
                  summary: Bad mobile number format
                  value:
                    status: error
                    message: >-
                      Field 'mobile' must be in E.164 format (e.g.,
                      +14155552671).
        '401':
          description: Unauthorized. Missing or invalid `x-api-key` header.
          content:
            application/json: {}
      security:
        - ApiKeyAuth: []
  /dynamic_auth/login:
    post:
      summary: Dynamic auth login
      description: >-
        Authenticate a device within the dynamic auth workflow by associating
        its machine and stock details. Often used after registration to
        initialize an operational session.
      operationId: loginDynamicAuth
      tags:
        - IotApis
      requestBody:
        description: >-
          Machine identifier and stock context for login. All properties must
          match the registration state for the device.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              validLogin:
                summary: Valid login for a registered device
                value:
                  machineId: MACHINE-001
                  stockName: ANDROID
                  totalPrice: '200.00'
                  currentStockPrice: '150.00'
      responses:
        '200':
          description: >-
            Login successful. A session for the device is now active in the
            system.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  value:
                    status: success
                    message: Login successful
        '400':
          description: >-
            Invalid login request (e.g., mismatched stock details, unknown
            device, or failed validations).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  value:
                    status: error
                    message: Invalid login credentials.
        '401':
          description: Unauthorized. Missing or invalid `x-api-key`.
          content:
            application/json: {}
      security:
        - ApiKeyAuth: []
  /dynamic_auth/verify:
    post:
      summary: Verify dynamic auth
      description: >-
        Verify whether a device is authentic/known to the dynamic auth system
        using its machine identifier. Use this to gate access to protected
        actions.
      operationId: verifyDynamicAuth
      tags:
        - IotApis
      requestBody:
        description: >-
          Payload containing the machine identifier to be verified. Note: this
          endpoint expects `machine_id` (snake_case).
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MachineIdVerifyRequest'
            examples:
              verifyExample:
                summary: Verify a known device
                value:
                  machine_id: MACHINE-001
      responses:
        '200':
          description: >-
            Verification successful. The provided device is recognized and
            allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  value:
                    status: success
                    message: Verification successful
        '400':
          description: >-
            Verification failed due to invalid input or the device is not
            recognized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  value:
                    status: error
                    message: Invalid machine ID provided.
        '401':
          description: Unauthorized. Missing or invalid `x-api-key`.
          content:
            application/json: {}
      security:
        - ApiKeyAuth: []
  /get/stock-price/{Symbol}:
    get:
      summary: Get stock price
      description: >-
        Fetch the latest price and associated exchange details for a given stock
        symbol. Intended for quick lookups used in dashboards or device
        displays.
      operationId: getStockPrice
      tags:
        - IotApis
      parameters:
        - $ref: '#/components/parameters/AcceptHeader'
        - name: Symbol
          in: path
          required: true
          description: >-
            Stock symbol to fetch price for. Symbols are case-insensitive
            alphanumeric strings used by the upstream provider.
          schema:
            type: string
          example: IBM
      responses:
        '200':
          description: Stock price retrieved successfully from the data provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockPriceResponse'
              examples:
                success:
                  value:
                    status: success
                    message: Stock price fetched successfully
                    data:
                      stockName: BSE Ltd
                      stockPrice: 2,162.50
                      stockExchangeName: BSE:National Stock Exchange of India
        '400':
          description: >-
            Invalid stock symbol (e.g., contains unsupported characters or not
            found by the provider).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  value:
                    status: error
                    message: Invalid stock symbol provided.
        '401':
          description: Unauthorized. Missing or invalid `x-api-key`.
          content:
            application/json: {}
      security:
        - ApiKeyAuth: []
components:
  parameters:
    AcceptHeader:
      name: Accept
      in: header
      description: >-
        Content type accepted by the client. Must be `application/json`. Some
        clients set this automatically; include explicitly for strict
        gateways.Defaults to `application/json` if not provided.
      required: false
      example: application/json
      schema:
        type: string
        enum:
          - application/json
  schemas:
    RegisterDynamicAuthRequest:
      type: object
      description: >-
        Payload for registering a device with stock details. All fields are
        required.
      properties:
        machineId:
          type: string
          description: >-
            Unique identifier for the machine. Allowed characters: letters,
            numbers, dot, hyphen, underscore.
          example: MACHINE-001
        stockName:
          type: string
          description: >-
            Name or code of the stock associated with the device
            (case-insensitive).
          example: ANDROID
        totalPrice:
          type: string
          description: >-
            Total price string for the stock (supports comma-separated thousands
            and up to 2 decimals). Example formats: `200.00`, `2,000.00`.
          example: '200.00'
        currentStockPrice:
          type: string
          description: >-
            Current market price as a string (same formatting rules as
            `totalPrice`).
          example: '150.00'
        machineName:
          type: string
          description: Human-readable display name for the machine.
          example: Testing-2
        mobile:
          type: string
          description: E.164 formatted mobile number for notifications and verification.
          example: '+917837582588'
      required:
        - machineId
        - stockName
        - totalPrice
        - currentStockPrice
        - machineName
        - mobile
    MachineIdRequest:
      type: object
      description: >-
        Request containing a machine ID for operations that target a single
        device.
      properties:
        machineId:
          type: string
          description: Unique identifier for the machine.
          example: MACHINE-001
      required:
        - machineId
    MachineIdVerifyRequest:
      type: object
      description: >-
        Request for verifying a machine. Note: this schema uses `machine_id` in
        snake_case.
      properties:
        machine_id:
          type: string
          description: Machine ID to verify against the registry.
          example: MACHINE-001
      required:
        - machine_id
    LoginRequest:
      type: object
      description: >-
        Request payload for dynamic auth login. All values must correspond to
        the registered state of the device.
      properties:
        machineId:
          type: string
          description: Unique identifier for the machine.
          example: MACHINE-001
        stockName:
          type: string
          description: Name/code of the stock used during login.
          example: ANDROID
        totalPrice:
          type: string
          description: Total price string (supports commas and up to 2 decimals).
          example: '200.00'
        currentStockPrice:
          type: string
          description: Current price string (supports commas and up to 2 decimals).
          example: '150.00'
      required:
        - machineId
        - stockName
        - totalPrice
        - currentStockPrice
    UpdateStockNameRequest:
      type: object
      description: Request payload for updating stock name.
      properties:
        machineId:
          type: string
          description: Unique identifier for the machine to update.
          example: MACHINE-001
        stockName:
          type: string
          description: The new stock name/code to associate.
          example: APPLE
      required:
        - machineId
        - stockName
    DevicesListResponse:
      type: object
      description: >-
        Response containing a list of devices available to the caller. The list
        may be empty if no devices are registered.
      properties:
        status:
          type: string
          description: Result indicator. `success` for successful retrieval.
          example: success
        message:
          type: string
          description: Human-readable status message.
          example: Devices retrieved successfully
        devices:
          type: array
          description: Array of device objects representing registered machines.
          items:
            type: object
            properties:
              machineId:
                type: string
                description: Unique ID of the device.
                example: MACHINE-001
              machineName:
                type: string
                description: Display name of the device.
                example: Testing-2
            required:
              - machineId
              - machineName
          example:
            - machineId: MACHINE-001
              machineName: Testing-2
            - machineId: kiosk-44A
              machineName: Entrance-Kiosk
      required:
        - status
        - message
        - devices
    StockPriceResponse:
      type: object
      description: >-
        Response containing stock price details as received from the provider or
        internal cache.
      properties:
        status:
          type: string
          description: Result indicator. `success` for successful retrieval.
          example: success
        message:
          type: string
          description: Human-readable message describing the result.
          example: Stock price fetched successfully
        data:
          type: object
          description: Stock information container.
          properties:
            stockName:
              type: string
              description: Display name of the stock.
              example: BSE Ltd
            stockPrice:
              type: string
              description: >-
                Price string formatted with optional commas and up to 2
                decimals.
              example: 2,162.50
            stockExchangeName:
              type: string
              description: Exchange name or code returned by the provider.
              example: BSE:National Stock Exchange of India
          required:
            - stockName
            - stockPrice
            - stockExchangeName
      required:
        - status
        - message
        - data
    SuccessResponse:
      type: object
      description: Standard success envelope returned by most endpoints.
      properties:
        status:
          type: string
          description: Indicates request success. Always `success` in this schema.
          example: success
        message:
          type: string
          description: Short description of the successful operation outcome.
          example: Operation completed successfully
      required:
        - status
        - message
    ErrorResponse:
      type: object
      description: >-
        Standard error envelope returned when a request fails validation, is
        unauthorized, or encounters a server error.
      properties:
        status:
          type: string
          description: Indicates failure. Always `error` in this schema.
          example: error
        message:
          type: string
          description: Detailed explanation of the error to help clients fix the request.
          example: Invalid request parameters
      required:
        - status
        - message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key required for authorization. Include in every request to
        authenticated endpoints.
security:
  - ApiKeyAuth: []
