> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/api-and-command-reference/qwantifi-api-and-command-reference/rms-mqtt-configuration-api-reference.md).
# RMS MQTT Configuration API Reference
This is the provisioning flow for QwantiFi: how RMS retrieves the latest QwantiFi configuration from the Magensa Gateway, generates the device command list, and hands it back so a client can apply it to a reader and report the result. For the architecture and server configuration behind this API, see the [**Web RMS Service**](https://rmsv2.developer.magtek.com/#919d6207-be9d-41b6-942b-c9dadb1aa66a).
## The Flow at a Glance
## Client POST Request: Request a Ronfiguration
The client requests one of three configuration names — `DynaFlexMqtt` (MQTT only), `DynaFlexTrust` (Trust/TLS only), or `DynaFlexMqttAll` (both).
```
POST {{RMSV2Url}}/V2/Configs
```
#### **Request**
```json
{
"ProductName": "DYNAFLEX",
"ProfileName": "MagTek_MQTT",
"ConfigurationName": "DynaFlexMqttAll",
"Version": null,
"FirmwareID": "1000009711-AC2-PCI",
"DeviceSerialNumber": "B563215",
"BillingLabel": "Test",
"InterfaceType": "USB",
"DownloadPayload": true,
"RawCommands": true,
"Authentication": null,
"AdditionalParameters": {
"KSN": "9070020B56C3AEE00000",
"Boot1FirmwareID": "",
"WifiFirmwareID": "",
"ResellerID": "13204",
"CustomerID": "2026213",
"DeviceNickname": "Store 101 Front Counter",
"Street1": "3674 Tyler Ave",
"Street2": "Suite 200",
"City": "El Monte",
"State": "CA",
"ZipCode": "91731",
"ZipPlus4": "2506",
"Country": "US"
}
}
```
`ResellerID`, `CustomerID`, and the Location fields are passed through in `AdditionalParameters`.
## Gateway Returns the Device's MQTT Hash and Status
RMS checks the device's current provisioning state against the Magensa Gateway.
```
GET {{gatewayUrl}}/MagensaMQTT/api/device-check?deviceSN={{deviceSn}}
```
#### **Response**
```json
{
"recordExists": true,
"mqttProvisioned": true,
"status": "Provisioned",
"deviceMqttHash": "8ebbeadebdc88d1ae6098179fe1940629d7ed2b9ba85c7eb3afb227d7d73257d"
}
```
## MQTT Configuration Version Control
* If `request.Version` is `0`, perform a **forced update** and return all configuration commands.
* Otherwise, compare the version-store hash with the database hash.
* If the hashes are identical, return a status of **Up To Date**.
* If the hashes differ, return the commands required to update the device.
## Gateway Returns Credentials
```
POST {{gatewayUrl}}/MagensaMQTT/api/credentials
```
#### **Request**
{% code overflow="wrap" %}
```json
{
"deviceSn": "B56C3AE",
"resellerId": "13204",
"customerId": "2026213",
"ksn": "9070020B56C3AEE00000",
"firmware": { "boot1": "1000008593-A1-PCI", "main": "1000008594-AA4-PRD", "wifi": "1000007537-AB2-PCI" },
"location": { "street1": "Pennsylvania Plaza", "street2": "", "city": "New York", "state": "New York", "zipCode": "10001", "zipPlus4": "", "country": "US" },
"nickname": "B56C3AE"
}
```
{% endcode %}
#### **Response**
```json
{
"deviceSn": "B563215",
"status": "PROVISIONED",
"mqttConfig": {
"broker": "10.0.5.151",
"port": 1883,
"peerCommonName": "",
"qos": 1,
"clientId": "B563215",
"username": "13204-2026213-B563215",
"password": "EXAMPLE-DUMMY-DEVICE-PASSWORD",
"subscribeTopic": "MagTek/13204/2026213/B563215/#",
"publishTopic": "MagTek/13204/2026213/device/publish/B563215",
"operatingMode": "mqtt"
}
}
```
{% hint style="info" %}
**Device credentials vs. integrated application credentials.** The credential above is a **device** credential — a per-device username and a plain password, with single subscribe/publish topics. This is different by design from anintegrated application credential (a short-lived JWT + refresh token, scope-wide wildcard topics). See the [**QwantiFi Credential Model**](https://developer.magtek.com/guides/guides/qwantifi/qwantifi-credential-model) for how the two differ.
{% endhint %}
## RMS Response to Client: The Commands
When the MQTT configuration differs from the device's configuration, the API returns the commands required to update the device. The `Commands` array contains the device commands (`DISPLAYMESSAGE`, `SENDCOMMAND`, `WAIT`, and optionally `SENDFILE`, `RESETDEVICE`) needed to apply the update.
{% code overflow="wrap" %}
```json
{
"Claims": {
"WlanProtocol": "00",
"Broker": "dev-mqtt.magensa.dev",
"Port": "8883",
"QoS": "1",
"SubscribeTopic": "MagTek/13204/2026213/B563215/SendCommand",
"PublishTopic": "MagTek/13204/2026213/device/publish/B563215",
"ClientId": "B563215",
"Username": "13204-2026213-B563215",
"Password": "******",
"PeerCommonName": "dev-mqtt.magensa.dev",
"OperatingMode": "mqtt"
},
"Name": "DynaFlex MQTT and Trust Configuration",
"Version": 3,
"ResultCode": 0,
"Result": "Success",
"MagTranIDs": [ "34cf8363-13c2-49b8-a70e-118d7529d452" ],
"Commands": [
"DISPLAYMESSAGE,Beginning DynaFlex MQTT Update...",
"SENDCOMMAND,AA0081040155D1118410D1118501018704020201018903D10100", // Updating WlanProtocol to 00
"SENDCOMMAND,AA0081040155D111844FD11185010187040202010289…", // Updating BrokerAddress
"SENDCOMMAND,AA0081040155D1118411D11185010187040202010289…", // Updating Port to 8883
"…", // QoS, SubscribeTopic, PublishTopic, ClientId, Username, Password, PeerCommonName
"DISPLAYMESSAGE,Updating Trust 05000100",
"WAIT,100",
"SENDCOMMAND,AA0081040101D8128444D812810405000100…", // Trust config command
"WAIT,100",
"SENDCOMMAND,AA00810804……", // Trust certificate (abbreviated)
"DISPLAYMESSAGE,Finished DynaFlex MQTT Update"
],
"ReleaseNotes": null
}
```
{% endcode %}
{% hint style="info" %}
**NOTE: Command bytes abbreviated.** The live `Commands` array is long: it repeats one `SENDCOMMAND` per setting and includes a full TLS certificate payload in the Trust command. It has been abbreviated here with `…` and inline comments. The commands are **generated by RMS**; integrators execute them as-is and do not author them by hand. Note also that the generated command list encodes the device password.
**Do not log or publish the raw command list!**
The settable configuration properties (Broker, Port, QoS, topics, Trust, etc.) are documented in [**QwantiFi Device Configuration Commands**](https://developer.magtek.com/api-and-command-reference/~/revisions/AxjZXnxcrmQygHeCLIf3/dynafamily-programmers-manual/mqtt-qwantifi-configuration-device-settings).
{% endhint %}
The Trust-only response (`ConfigurationName: DynaFlexTrust`) has the same shape but a much shorter `Commands` array — the Trust/TLS command(s) only.
## Client Confirms Device Update Status
After applying the commands, the client reports success or failure back to RMS.
```
POST {{RMSV2Url}}/V2/Configs/UpdateDeviceStatus
```
#### **Request**
```json
{
"ProductName": "DYNAFLEX",
"ProfileName": "MagTek_MQTT",
"ConfigurationName": "DynaFlexMqttAll",
"FirmwareID": "1000009712-AC3-PRD",
"DeviceSerialNumber": "B62CA5F",
"Operation": "UpdateMQTTConfigurations",
"Authentication": null,
"AdditionalParameters": { "ResellerID": "13204", "CustomerID": "2026213" },
"ResultCode": 0,
"Result": "Success",
"ResultDetails": "",
"MagTranIDs": [ "0455ef05-4b00-45d9-a312-92877b5f0b04" ]
}
```
On success, RMS updates the version store with the latest configuration version and MQTT hash, and records the update status in the log.
## Trust Version control
For Trust configuration:
* If `request.Version` is `0`, perform a forced update and return all configuration commands.
* Otherwise, compare the device version with the configuration file version.
* If `request.Version` is `null`, use the stored version as the device version for comparison.
* If the device version matches the configuration version, return a status of **Up To Date**.
* If the device version is lower, return the commands required to update to the latest configuration.
## Gateway Confirms Device Status
RMS marks the device's status in the Gateway database.
```
PATCH {{gatewayUrl}}/api/confirm-device-status
```
#### **Request**
```json
{ "deviceSn": "B56C3AE" }
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://developer.magtek.com/api-and-command-reference/qwantifi-api-and-command-reference/rms-mqtt-configuration-api-reference.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
