Architecture Overview

availability

Feature availability by platform, plan type, and user type

Platform:	AvailableWebNot availableMobile
Plan Type:	Not availableBasicNot availableEssentialAvailablePremiumAvailableEnterprise
User Type:	Not availableRequesterNot availableFull UserAvailableAdministrator

This article provides an overview of the Kepware IoT Gateway connector architecture, focusing on how it connects to MaintainX®, its security characteristics, and how tag data is structured.

How It Connects

You configure the Kepware agent within Kepware's IoT Gateway Plugin. The agent collects tag readings from your Kepware ServerEx6 and sends them to MaintainX as HTTPS POST requests at a configurable interval. Your OT devices communicate only with Kepware and are never exposed to the internet directly.

Kepware IoT Gateway Connector Data Flow

The MaintainX platform receives each POST, parses the tag readings, and associates them with the corresponding connector instance using the access token in the request header.

Security

Read-Only Access

The Kepware connector operates in read-only mode. MaintainX receives tag values from Kepware but never sends commands or writes data back to Kepware or any OT device. Your OT environment is not affected by MaintainX connectivity.

Secure Outbound Communication

The Kepware agent initiates all communication outbound from your network. MaintainX never opens a connection into your network, so no inbound firewall ports are required.

Network requirements:

Parameter	Value
Protocol	HTTPS (TLS)
Direction	Outbound only
Destination URL	For more information, see On-Premise requirements for your region's endpoint.
Port	443

Token Authentication

Every request from Kepware to MaintainX is authenticated using a bearer token included in the HTTP Authorization header. The token is generated in MaintainX when you create a connector instance and is unique to that instance. MaintainX validates the token on every incoming request.

The token is displayed only once at creation time. If a token is lost or compromised, it can be revoked and replaced without affecting other connector instances. For instructions, see Revoke and Regenerate a Kepware Access Token.

OT Network Isolation

Your OT devices (PLCs, sensors, etc.) communicate only with Kepware over your internal OT network. Kepware processes the raw OT data and sends only structured tag readings to MaintainX; raw OT traffic never leaves your network. This preserves the OT/IT boundary that enterprise security requirements typically mandate.

Tag Data Structure

Tag Naming: Channel.Device.Tag

Kepware organizes data points into a three-level hierarchy:

Kepware Tag Hierarchy

When the Kepware agent sends a reading to MaintainX, the full Channel.Device.Tag path is used as the tag identifier.

For example, a tag at McHenryPLC.101-11.HopperGate in Kepware appears under that same name in MaintainX. This name is what the smart tag mapping system uses to suggest meter names and asset associations.

For more on the tag hierarchy, see Tags and Tag Hierarchy.

Payload Format

The Kepware IoT Gateway sends tag readings in a fixed JSON format. MaintainX parses this format to extract readings. The message template in the Kepware agent must not be modified. MaintainX only accepts the default Kepware payload structure.

Each POST body contains a batch of tag value records:

{
  "timestamp": 1741015474200,
  "values": [
    {
      "id": "Channel.Device.Tag",
      "v": 38.04,
      "q": true,
      "t": 1741015465070
    }
  ]
}

Field	Description
id	The full Channel.Device.Tag path. Used as the tag identifier in MaintainX.
v	The tag value at the time of the reading.
t	The Unix timestamp (milliseconds) for the reading. Used by MaintainX to record when the value was sampled.
q	Tag quality flag from Kepware (OPC quality codes: 192 = Good, 0 = Bad). Currently received but not surfaced in MaintainX.

warning

The outer timestamp field in the payload envelope isn't used by MaintainX. The per-value t field is the authoritative timestamp for each reading.