Inventory Management

The inventory is the central database of all endpoints managed by IDIAL. It stores connection parameters, credentials, certificate status, and PKI assignment for each managed device. The inventory is the primary data source for monitoring dashboards and certificate lifecycle operations.

note

The inventory contains cached information from the last monitoring run — not live data from the endpoints. To refresh the data, trigger a monitoring run for the relevant endpoints via POST /gds/monitor/crt.

The service field identifies the connection protocol for each entry:

gds-push-<identifier> — OPC UA GDS Push protocol. IDIAL supports multiple GDS Push endpoints from different manufacturers and firmware versions. Since the OPC UA information model can vary significantly, IDIAL maintains a list of tested devices and their firmware versions. The <identifier> is manufacturer- and firmware-specific.
ssh-<identifier> — SSH-based certificate management. The <identifier> is an alphanumeric identifier that defines the endpoint type. IDIAL can support multiple SSH-connected endpoints, where the SSH commands differ depending on the endpoint type.
rest-<identifier> — REST API-based certificate management. Since each REST API is vendor-specific, the <identifier> is a unique identifier for a particular REST API that has been developed and tested for IDIAL.

GET /inventory

Returns the complete list of all inventory entries across all service types (GDS, SSH, PKI, etc.). This endpoint is the central monitoring and reporting endpoint. The returned information can be used to feed monitoring services integrated into operational monitoring and incident management platforms.

IDIAL does not evaluate the information — it merely provides it. It is the responsibility of the REST client to interpret and process the information. This allows customers to integrate the monitoring information into their internal asset management, change management, and incident management processes.

The endpoint has no dependencies on other IDIAL services.

Authentication: Required (X-API-Key)

Response 200

Array of inventory objects:

[
  {
    "id": 1,
    "name": "Siemens PLC Line 1",
    "url": "opc.tcp://192.168.1.10:4840",
    "service": "gds-push-siemens",
    "server": "192.168.1.10",
    "port": 4840,
    "device_status": 1,
    "device_status_name": "Active",
    "pki_endpoint": "est-production",
    "username": "admin",
    "cert_subjectdn": "CN=plc-line1,O=ExampleCorp,C=DE",
    "cert_issuerdn": "CN=Issuing CA,O=ExampleCorp,C=DE",
    "cert_validfrom": "2025-01-01 00:00:00",
    "cert_validto": "2026-01-01 00:00:00",
    "cert_certb64": "MIIDxDCC...",
    "cert_expdays": 276,
    "cert_revoked": false
  }
]

Response Fields

Field	Type	Description
`id`	integer	Unique identifier of the inventory entry
`name`	string	Human-readable name of the endpoint
`url`	string	Full connection URL (e.g., `opc.tcp://host:port`). Built internally by IDIAL and returned for transparency and troubleshooting of connection issues.
`service`	string	Service type identifier (see service types above)
`server`	string	IP address or DNS FQDN of the endpoint. IDIAL uses this value to build the connection URL. If a DNS FQDN is provided, it must be resolvable by IDIAL.
`port`	integer	Network port of the certificate management service on the endpoint.
`device_status`	integer	`0` = Inactive, `1` = Active (see Parameter Reference). When `0`, IDIAL monitors the endpoint but does not trigger any certificate or trust list updates.
`device_status_name`	string	Human-readable status name
`pki_endpoint`	string	Configured endpoint ID of the enrollment target for this asset. Each EST endpoint provides enrollment functionality for a specific certificate template. The PKI configuration contains the endpoint information.
`username`	string	Configured username for authentication at the endpoint, if a username has been defined.
`cert_subjectdn`	string	Subject DN of the certificate currently active on the endpoint.
`cert_issuerdn`	string	Issuer DN of the certificate currently active on the endpoint. Indicates which CA issued the certificate.
`cert_validfrom`	string	Date and time of the start of validity of the certificate currently active on the endpoint.
`cert_validto`	string	Date and time of the end of validity of the certificate currently active on the endpoint.
`cert_certb64`	string	Base64-encoded digital certificate identified by IDIAL on the endpoint.
`cert_expdays`	integer	Days until expiry of the identified certificate. This value is calculated by IDIAL based on the `cert_validto` field and the current IDIAL system time.
`cert_revoked`	boolean	Indicates whether the certificate has been revoked.

note

The inventory contains no live data, but the information that IDIAL recorded during the last monitoring run against the endpoint. To obtain the most current data for all endpoints, monitoring tasks should be executed for all endpoints — taking care to ensure that the load on the endpoints does not impact ongoing operations.

Error Response

{"error": "string"}

POST /inventory

Creates a new inventory entry or updates an existing one. IDIAL uses UPSERT logic: the generated connection URL is the unique key — if an entry with the same URL already exists, it is updated; otherwise, a new entry is created.

The endpoint validates input data at multiple levels: schema validation, business logic checks, and database integrity checks. All passwords are automatically encrypted with the system encryption key before storage. Critical validations include: protocol support check, key-value format parsing, URL uniqueness check across all database tables, and PKI configuration validation.

Authentication: Required (X-API-Key)

Request Body

{
  "protocol": "GDS Push",
  "host": "192.168.1.10",
  "port": 4840,
  "userinfo_name": "admin",
  "userinfo_password": "secret",
  "device_status": 1,
  "pki": 1,
  "security_policy": 8,
  "security_mode": 2
}

Request Fields

Field	Type	Required	Default	Description
`protocol`	string	Yes	`"GDS Push"`	Communication protocol for device integration. Currently only `"GDS Push"` is supported. Case-insensitive: `"gds push"`, `"GDS Push"`, and `"GDS PUSH"` are equivalent.
`host`	string	Yes	`"localhost"`	FQDN or IP address of the target device. Used to establish the connection to the target endpoint.
`port`	integer	No	`4840`	Port on which the target endpoint is listening. Default: `4840` (standard OPC UA port).
`userinfo_name`	string	No	—	Username for OPC UA authentication. Can be an empty string.
`userinfo_password`	string	No	—	Password for OPC UA authentication. Encrypted before storage. No password strength validation is performed.
`device_status`	integer	No	`1`	Status indicator of the target device. `0` = Inactive, `1` = Active. When set to `0` (Inactive), IDIAL monitors the endpoint's certificate but does not trigger any certificate or trust list updates.
`pki`	integer	No	—	PKI configuration ID. The PKI endpoint configuration is referenced via an identifier. The available IDs can be retrieved via `GET /pki/est`.
`security_policy`	integer	No	`31`	OPC UA Security Policy bitmask (see Parameter Reference)
`security_mode`	integer	No	`0`	OPC UA Security Mode (see Parameter Reference)

Response 200

{"success": true, "execution": "...", "error": "", "result": {...}}

Error Codes

Code	Error Type	Description
400	Invalid data format	The request body contains invalid data types or a malformed structure. The input data could not be processed due to formatting errors.
500	Inventory service unavailable	The inventory system is temporarily unreachable or experiencing issues.
500	Device configuration conflict	The device configuration conflicts with existing inventory entries.
500	Invalid PKI configuration	The specified PKI configuration does not exist or is invalid.
500	Device registration failed	The device could not be added to or updated in the inventory system.
500	Invalid service response	The inventory service returned an unexpected response format.
501	Unsupported protocol	The submitted protocol is not supported by IDIAL in this version. Please use only supported certificate management protocols.

PATCH /inventory

Updates an existing inventory entry. Uses the same schema as POST /inventory. Only the submitted fields are updated.

Authentication: Required (X-API-Key)

GET /gds/inventory

Returns all GDS Push inventory entries.

Authentication: Required (X-API-Key)

Response 200

Array of inventory objects (same schema as GET /inventory, filtered to GDS entries).

POST /gds/inventory

Creates a new GDS Push inventory entry.

Authentication: Required (X-API-Key)

Request Body

{
  "server": "192.168.1.10",
  "port": 4840,
  "name": "PLC Line 1",
  "userinfo_name": "admin",
  "userinfo_password": "secret",
  "device_status": 1,
  "pki": 1,
  "security_policy": 8,
  "security_mode": 2,
  "renewal_days": 30
}

Request Fields

Field	Type	Required	Default	Description
`server`	string	Yes	—	IP address or FQDN
`port`	integer	No	`4840`	OPC UA port
`name`	string	No	—	Human-readable name of the endpoint
`userinfo_name`	string	No	—	OPC UA username
`userinfo_password`	string	No	—	OPC UA password (stored encrypted)
`device_status`	integer	No	`1`	`0` = Inactive, `1` = Active
`pki`	integer	No	—	PKI configuration ID
`security_policy`	integer	No	`31`	Security policy bitmask
`security_mode`	integer	No	`0`	Security mode
`renewal_days`	integer	No	—	Days before expiry at which automatic renewal is triggered

Response 200

Created or updated inventory object.

PATCH /gds/inventory

Updates an existing GDS inventory entry. Uses the same schema as POST /gds/inventory. Only the submitted fields are updated.

Authentication: Required (X-API-Key)

GET /gds/inventory/{host_or_url}

Returns a specific GDS inventory entry by server hostname, IP address, or full OPC UA URL.

Authentication: Required (X-API-Key)

Path Parameters

Parameter	Description
`host_or_url`	Server hostname, IP address, or full OPC UA URL (URL-encoded if necessary)

Response 200

Single inventory object.

Response 404

Entry not found.

Example

curl -X GET "http://localhost:5000/gds/inventory/192.168.1.10" \
  -H "X-API-Key: your-api-key"

GET /ssh/inventory

Returns all SSH-based inventory entries. SSH connections are used for certificate management on devices that do not support OPC UA GDS.

Authentication: Required (X-API-Key)

Response 200

Array of inventory objects filtered to SSH entries (same schema as GET /inventory).

Examples

# Retrieve all inventory entries
curl -X GET http://localhost:5000/inventory \
  -H "X-API-Key: your-api-key"

# Add a new GDS device
curl -X POST http://localhost:5000/gds/inventory \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.10",
    "port": 4840,
    "name": "PLC Line 1",
    "userinfo_name": "admin",
    "userinfo_password": "secret",
    "device_status": 1,
    "security_policy": 8,
    "security_mode": 2
  }'

# Retrieve a specific entry
curl -X GET "http://localhost:5000/gds/inventory/192.168.1.10" \
  -H "X-API-Key: your-api-key"

GET /inventory​

Response 200​

Response Fields​

Error Response​

POST /inventory​

Request Body​

Request Fields​

Response 200​

Error Codes​

PATCH /inventory​

GET /gds/inventory​

Response 200​

POST /gds/inventory​

Request Body​

Request Fields​

Response 200​

PATCH /gds/inventory​

GET /gds/inventory/{host_or_url}​

Path Parameters​

Response 200​

Response 404​

Example​

GET /ssh/inventory​

Response 200​

Examples​

GET /inventory

Response 200

Response Fields

Error Response

POST /inventory

Request Body

Request Fields

Response 200

Error Codes

PATCH /inventory

GET /gds/inventory

Response 200

POST /gds/inventory

Request Body

Request Fields

Response 200

PATCH /gds/inventory

GET /gds/inventory/{host_or_url}

Path Parameters

Response 200

Response 404

Example

GET /ssh/inventory

Response 200

Examples