Set up the Shadow API
Learn what the Shadow API does and configure its MQTT broker connection, authentication, QoS, SSL, and certificates in the next-generation Edge Portal.
The Shadow API lets a remote application access the internal SIA Connect REST API through MQTT. It acts as a proxy between an MQTT broker and the gateway. A client publishes a correctly formatted API request to a subscribed MQTT topic, the gateway processes the request, and the Shadow API publishes the response back through the broker.
This is useful when direct HTTP access to a gateway is unavailable, such as when the gateway is behind a firewall or on a network with restricted inbound access.
You need an MQTT broker that the gateway can reach. Collect its address, port, required topics, credentials, and TLS certificate requirements from the broker administrator.
Open the Shadow API settings
- Sign in to the Edge Portal.
- Expand Tools in the sidebar.
- Select Shadow API.
The page contains General settings for the MQTT connection and SSL settings for transport security.
Configure the general settings
| Parameter | Description |
|---|---|
| Address | The hostname or IP address of the MQTT broker. This field is required and can contain up to 255 characters. |
| Port | The MQTT broker port. Enter digits only and use a value from 1 through 65535. Use the port configured by the broker administrator. |
| Username | The username used to connect to the MQTT broker. Leave it empty only when the broker permits a connection without a username. The maximum length is 120 characters. |
| Password | The password used with the MQTT broker username. The maximum length is 120 characters. |
| Sub topics | The MQTT topic or topics on which the Shadow API listens for requests. Multiple values can be entered as a comma-separated list. The maximum length is 255 characters. |
| ClientID | The MQTT client identifier used by this gateway. It must identify the connection as required by your broker and must not be empty. The maximum length is 120 characters. |
| QoS | The MQTT quality of service level. 0 sends a message at most once, 1 sends it at least once, and 2 delivers it exactly once. The default value for a new configuration is 1. |
| Require API authentication | Controls whether requests forwarded to the SIA API must include API authentication. This is separate from the MQTT broker username and password. Keep this enabled unless unauthenticated API access is explicitly required for your integration. |
Configure SSL settings
Use SSL settings when the MQTT broker requires an encrypted connection or certificate-based client authentication.
| Parameter | Description |
|---|---|
| SSL version | Select None, 1.0, 1.1, or 1.2. Select the version supported by your broker. Use 1.2 when possible. Selecting None disables SSL for this connection. |
| Client certificate | The certificate presented by the gateway when the broker uses certificate-based client authentication. |
| Client key | The private key that belongs to the uploaded client certificate. |
| Server certificate | The certificate used to establish trust in the MQTT broker. |
| Verify server CA | Select Yes to validate the broker certificate against the configured server certificate. Use No only when validation is intentionally disabled for a controlled environment. |
Select an upload button to choose a new certificate or key. The page shows the current or selected filename. Select the remove control beside a filename to clear that field. A stored or selected filename can contain up to 255 characters.
The client key is sensitive. Store and transfer it securely, and use only the certificate and key pair supplied for this gateway.
Save and connect
- Review the general and SSL settings.
- Select Save and Connect.
- Wait for the confirmation that the Shadow API settings were saved for the configured ClientID.
The Edge Portal saves the settings, uploads any newly selected certificate files, and requests a restart of the Shadow API service so the changes can take effect.
On a Docker installation, the Web GUI & Shadow API container is restarted. Some Docker installations do not allow one container to restart another. If the Edge Portal displays this warning and the new configuration does not take effect, restart the container that contains the Shadow API manually.
Test the connection
After saving, publish a valid Shadow API request to one of the configured subscription topics. Confirm that the broker receives a response on the target topic specified in the request.
The setup page configures the broker connection. The request JSON format, API authentication header, response topics, and command examples are documented in Using the Shadow API.
Troubleshoot the setup
| Message or symptom | What to do |
|---|---|
| Please fix the highlighted fields before continuing. | Check every highlighted field. Address and ClientID are required. Port must contain digits only and be between 1 and 65535. Check the displayed length limit for text and filename fields. |
| Failed to load saved Shadow API settings. | You can still enter and save a new configuration. If the message continues, verify communication with the gateway and review the system logs. |
| Failed to save Shadow API settings. | Verify communication with the gateway, check that certificate files can be read, and try again. Review the logs if the error continues. |
| Settings save, but the connection does not start | Confirm that the address, port, ClientID, credentials, topics, QoS, and SSL settings match the broker. Verify DNS and network routing from the gateway to the broker. On a Docker installation, restart the container that contains the Shadow API if the automatic restart was blocked. |
| TLS connection fails | Confirm that the selected SSL version is supported by the broker. Check that the client certificate matches the client key, that neither has expired, and that the correct server certificate is installed. If Verify server CA is enabled, ensure the broker certificate can be validated. |
| The broker receives no requests or responses | Check that the client publishes to a configured subscription topic and that each request defines the correct target response topic. Confirm broker permissions for publishing and subscribing. |
| The API returns an authentication error | When Require API authentication is enabled, include a supported authorization header in the Shadow API request. Broker credentials do not replace SIA API credentials. |