SDEX Suite – OpenAPI Specifications

OpenAPI 3.0 specifications, interactive Swagger documentation, and automation examples for the Softing SDEX Suite REST API — an industrial connectivity gateway that exposes OPC UA server/client, MQTT, and PLC connections through an HTTP API.

Browse the API Documentation

Hosted Swagger UI portal: https://softingindustrial.github.io/SDEXapi/

Use the API dropdown (top bar, "Select a definition") to switch between the Linux and Windows variants of the API.

Repository Structure

File	Description
index.html	Self-contained Swagger UI portal (loads swagger-ui-dist from CDN). Renders both JSON specs with a definition-switcher dropdown. This is the page deployed to GitHub Pages.
SDEX Suite Linux.json	OpenAPI 3.0 spec (JSON) for the Linux/Docker distribution of SDEX Suite. This is the file consumed by index.html.
SDEX Suite Windows.json	OpenAPI 3.0 spec (JSON) for the Windows distribution.
SDEX Suite Linux-oas3.yml	YAML version of the Linux spec — content-identical to the JSON file. Convenient for code generators, diffing, and manual editing.
SDEX Suite Windows-oas3.yml	YAML version of the Windows spec.
user-guide.md	Step-by-step API user guide: prerequisites, container startup, nonce-based authentication (login, Auth header construction, token refresh, mandatory default-password change), and worked curl examples for OPC UA client connections, OPC UA server endpoints, address spaces, certificate management (PKI sessions), Siemens S7 1200/1500 and PLCs connections and MQTT connections/pub/sub requests. Start here if you are new to the API.
prepareContainers.sh	Convenience script that (re)creates the SdexSuite Docker container from the softingindustrial/sdex-suite image and maps the required ports.
demo.sh	End-to-end automation example (Bash + curl + python3). Resolves the container IP, logs in with the default admin user, builds the signature Auth header, changes the default password, then exercises the API: PLCs connections, MQTT connection + pub/sub requests, token refresh, OPC UA client connections, certificate/PKI-session handling, OPC UA server endpoints, user/group mapping, cleanup, and logout. Use it as a reference implementation for scripting against the API — especially the build_auth_header() function.
.gitlab-ci.yml	CI pipeline with a single manual mirror:toGithub job that mirrors the internal GitLab main branch (all branches + tags) to github.com/SoftingIndustrial/SDEXapi.

Quick Start (Linux + Docker)

Prerequisites: Docker Engine, bash, curl, python3.

1. Start the SDEX Suite container

   ./prepareContainers.sh

   This runs:

   docker container run -d -p 1443:443 -p 8099:8099 -p 4800-5000:4897 \
     --name SdexSuite softingindustrial/sdex-suite

   Host port	Container port	Purpose
   1443	443	HTTPS REST API
   8099	8099	HTTP REST API (uacore module)
   4800–5000	4897	OPC UA server endpoint (opc.tcp)

2. Run the demo

   ./demo.sh

   demo.sh talks to the container's internal IP directly (https://<container-ip>:443), so it must run on the Docker host (Linux). On Docker Desktop (macOS/Windows) use https://localhost:1443 instead.

3. Explore further — follow user-guide.md for individual, explained curl calls.

Authentication at a Glance

The API uses nonce-based authentication (no bearer tokens):

1. POST /runtime/core/auth/by-password with name, password, and a Base64 clientNonce → server returns a serverNonce and the user id.
2. Compute the signature: Base64( SHA-256( decode(serverNonce) + decode(clientNonce) ) ).
3. Send every authenticated request with the header Auth: User=<url-encoded-username>;Signature=<url-encoded-signature>.
4. Refresh sessions via POST /runtime/core/auth/refresh-token (returns a newServerNonce; recompute the signature with it).

Changing the default admin password is mandatory. Until it is changed, most authenticated calls are rejected with HTTP 406 – Default user password was not changed. See the Authentication and Login section of the user guide.

The build_auth_header() function in demo.sh implements the full signature workflow and can be copied into your own scripts.

API Overview

Both specs (Linux/Windows) expose endpoints under /runtime/..., grouped as:

• Core — authentication, user/group management, LDAP, licensing, audit log, log files/traces, configuration up/download, system status, support data, versioning
• UaCore — application identity, namespaces, NodeSet XML, address spaces ("sights"), node filtering, subscription/monitored-item options
• Module endpoints used in the guide/demo (opcua-client, opcua-server, httpua-server, mqtt, siemenss72, siemenss32, allenbradley, modbus, fanuc, sinumerik840d) are documented by example in user-guide.md

Related Links

• Hosted API docs: https://softingindustrial.github.io/SDEXapi/
• Docker image: softingindustrial/sdex-suite
• GitHub mirror: https://github.com/SoftingIndustrial/SDEXapi