Table of contents
1. Intro: login and logout
1.1) REST API to manage MQTT service
1.2) Login into the API and getting a tokenId
1.3) Logout from the API (cancelling tokenId)
2. User management
2.1) Change my password (for a logged device)
2.2) Get user information (for a logged device)
3. Domain and device management
3.1) Get connected devices to your domain (for a logged domain admin device)
3.2) List domains (MyQtt contexts) (for a logged domain admin device)
3.3) List devices (for a domain) (for a logged domain admin device)
3.4) Add device (to a domain) (for a logged domain admin device)
3.5) Remove device (from a domain) (for a logged domain admin device)
4. IP security
4.1) List allowed ips for current logged device
4.2) Add allowed ip for current logged device
4.3) Remove allowed ip for current logged device
5. Subscription management
5.1) Subscribe topic for current logged device
5.2) Unsubscribe topic for current logged device
5.3) Get current subscriptions for current logged device
5.4) List domain subscriptions
5.5) Administrative/domain subscribe
5.6) Administrative/domain unsubscribe
6.Publishing and getting messages
6.1) Publish message for a current logged device
6.2) Pull messages for a current logged device
6.3) Pull messages with acknowledgement (pull with ack)
6.4) Request/response (MQTT v5) for a current logged device
6.5) Publish to a domain (for a logged domain admin device)
7.Handling filters
7.1) List filters
7.2) Create filter
7.3) Remove filter
8.Stashing
8.1) Stash download
8.2) List stashes
8.3) View a stash
8.4) Add or update a stash
8.5) Remove a stash
8.6) Get stashed messages
8.7) Clear stashed messages
8.8) Remove or replay a stashed message
9.Domain security
9.1) Get domain security settings
9.2) Change domain security settings
9.3) SCRAM status of the devices of a domain
REST API to manage MQTT service
Next you will find the description of the REST API available for your service.
To interface with it you will need:
- A valid clientId + userName + password to log into the service and get a tokenId.
- All services use the POST method against the node that runs your hub (for example, https://node02.myqtthub.com).
- Some services require domain administration credentials. Others can be used by regular devices.
- All message bodies are encoded using JSON. Fields shown between brackets (
[field]) are optional. - Except /login, every request must send the tokenId in a cookie named
tokenId, and it is recommended to send it also inside the JSON body ("tokenId").
When a request fails, a 400 Bad Request is received with a text body explaining the error (expired token, missing rights, wrong parameters…).
Login into the API and getting a tokenId
Service: POST /login
Message: {“clientId” : string, “userName” : string, “password” : string, “cleanSession” : boolean}
Example:
>> curl -X POST https://node02.myqtthub.com/login -d ‘{“clientId” : “testId”, “userName” : “aUserName”, “password” : “test1234”, “cleanSession” : false }’
If login succeeds, 200 OK is received with a body like:
{“clientId”:“testId”,“cleanSession”:false,“tokenId”:“0da82260-207e-4e4e-9fc3-d2846d7c54f0”,“stamp”:1531410287,“validUntil”:1531583087}
stamp and validUntil are Unix timestamps (seconds): by default, a tokenId is valid for 48 hours.
If login fails, 403 Forbidden is received with body:
Service denied (auth login failure, wrong password, identifier rejected or connection refused)
You will have to use this tokenId for the rest of the services: send it as a cookie and as a parameter.
A login works like an MQTT connection with the same clientId: a new login with a clientId that already has an HTTP session replaces that session. The previous tokenId stops working and the messages it had pending to pull are discarded (see Pull messages). Avoid having two processes logged with the same clientId.
Logout from the API (cancelling tokenId)
Service: POST /logout
Message: {“tokenId” : string}
Cookie: tokenId
Example:
>> curl --cookie “tokenId=0da82260-207e-4e4e-9fc3-d2846d7c54f0” -X POST https://node02.myqtthub.com/logout -d ‘{“tokenId” : “0da82260-207e-4e4e-9fc3-d2846d7c54f0”}’
If logout succeed, 200 Ok code is received with body example:
Logout completed
If logout fails, 400 Bad request is received with body example:
Failed to complete request, error was: java.lang.Exception: Authentication failure, failed to complete operation, error was: Token not valid, expired or login session needed
Change my password (for a logged device)
Service: POST /change-my-password
Message: {“newPassword” : string, “tokenId” : string}
Cookie: tokenId
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Get user information (for a logged device)
Service: POST /user/info
Message: {“tokenId” : string}
Cookie: tokenId
Returns the session information associated to the logged device.
Service result:
Correct finalization: 200 OK {“clientId” : string, “ip” : string, “userName” : string, “domainName” : string, “isAdmin” : boolean, “hasDomainAdmin” : boolean, “cleanSession” : boolean, [“plan” : object], [“messageStats” : object]}
Failure: 400 Bad request
plan and messageStats report the plan of your hub and its message counters, when available.
Get connected devices to your domain (for a logged domain admin device)
Service: POST /devices/connected
Message: {“tokenId” : string}
Cookie: tokenId
Returns the list of devices connected to your domain. Needs the tokenId of a domain administrator.
Service result:
Correct finalization: 200 OK [{“domainName” : string, “clientId” : string, “userName” : string, “cleanSession” : boolean, “traceBytes” : boolean, “remoteAddress” : string, “connectedAt” : number, “numTopics” : number, “protocol” : string, “isBridge” : boolean, “bootStrapped” : boolean, “mqttVersion” : string}, …]
Failure: 400 Bad request
protocol is the transport used by the device (mqtt, mqtt-tls, mqtt-ws, http…) and mqttVersion the MQTT version of its connection (“3.1.1” or “5.0”).
List domains (MyQtt contexts) (for a logged domain admin device)
Service: POST /domain/list
Message: {“tokenId” : string}
Cookie: tokenId
Returns a list of all domains for which the user has domain administration rights
Service result:
Correct finalization: 200 OK [{“domain” : string, “plan” : string, “isActive” : boolean, “logReporting” : boolean}, …]
Failure: 400 Bad request
List devices (for a domain) (for a logged domain admin device)
Service: POST /device/list
Message: {“domainName” : string, “tokenId” : string}
Cookie: tokenId
Returns the list of devices registered into the given domain.
Service result:
Correct finalization: 200 OK [{“clientId” : string, [“userName” : string], “isActive” : boolean, “isDomainAdmin” : boolean, “freezeSubscriptions” : boolean, “skipReplace” : boolean, “connectionHistory” : boolean, “sciAuthEnabled” : boolean, [“sciAuth” : string], “skipSessionIpEnforce” : boolean}, …]
Failure: 400 Bad request
Add device (to a domain) (for a logged domain admin device)
Service: POST /device/add
Message: {“domainName” : string, “clientId” : string, [“userName” : string], [“password” : string], “tokenId” : string}
Cookie: tokenId
Creates a new device.
Service result:
Correct finalization: 200 OK device created
Failure: 400 Bad request
Remove device (from a domain) (for a logged domain admin device)
Service: POST /device/remove
Message: {“domainName” : string, “clientId” : string, “tokenId” : string}
Cookie: tokenId
Removes the device selected by clientId from the given domain. A device cannot remove itself.
Service result:
Correct finalization: 200 OK device removed
Failure: 400 Bad request
List allowed ips for current logged device
Service: POST /ip/allowed/list
Message: {“domainName” : string, “clientId” : string, “tokenId” : string}
Cookie: tokenId
Allows to list the IPs from which a device is allowed to log in. If no IP is registered, the device is allowed to log in from any IP. After the first IP is added, the platform starts limiting logins for that device. The current login is not limited by this service.
domainName and clientId select the device: domain administrators can manage any device of their domains, while regular devices always manage their own list (send their own domainName and clientId).
Service result:
Correct finalization: 200 OK [[ip, active], [next-ip], …]
Failure: 400 Bad request
Add allowed ip for current logged device
Service: POST /ip/allowed/add
Message: {“domainName” : string, “clientId” : string, “remoteAddr” : string, “tokenId” : string}
Cookie: tokenId
Allows to add a new remoteAddr IP from which the device is allowed to log in (see List allowed ips for domainName and clientId).
Service result:
Correct finalization: 200 OK ip added
Failure: 400 Bad request
Remove allowed ip for current logged device
Service: POST /ip/allowed/remove
Message: {“domainName” : string, “clientId” : string, “remoteAddr” : string, “tokenId” : string}
Cookie: tokenId
Allows to remove a remoteAddr IP from the list of IPs allowed for the device. If all IPs are removed, the device can log in from any IP.
Service result:
Correct finalization: 200 OK ip removed
Failure: 400 Bad request
Subscribe topic for current logged device
Service: POST /subscribe
Message: {“subscriptions” : [[string, int], [next-subscribe], …], [“options” : object], “tokenId” : string}
Cookie: tokenId
Each position of the list includes a [topicToSubscribe, qosToSubscribe].
Allows to subscribe to a list of topics for the current logged device. The service returns the subscription codes granted (QoS granted, or an error code).
options (optional) applies MQTT v5 subscription options to all the subscriptions of the request: {[“noLocal” : boolean], [“retainAsPublished” : boolean], [“retainHandling” : 0 | 1 | 2], [“subscriptionIdentifier” : int]}.
Service result:
Correct finalization: 200 OK [int, …]
Failure: 400 Bad request
Unsubscribe topic for current logged device
Service: POST /unsubscribe
Message: {“subscriptions” : [string, …], “tokenId” : string}
Cookie: tokenId
The service receives the list of topics to unsubscribe.
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Get current subscriptions for current logged device
Service: POST /get-subscriptions
Message: {“tokenId” : string}
Cookie: tokenId
Returns the list of subscriptions of the current logged device.
Service result:
Correct finalization: 200 OK [[topic, qos, online, [options]], …]
Failure: 400 Bad request
Each subscription is reported as [topic filter, QoS, online]. A fourth item with the MQTT v5 subscription options is added when any of them is not the default value (see Subscribe topic).
List domain subscriptions
Service: POST /get-domain-subscriptions
Message: {“domainName” : string, “tokenId” : string}
Cookie: tokenId
This API needs administration rights (API user must have administrator rights at the destination HUB).
Allows to list all subscriptions that are currently installed and running for a given MyQttHUB (selected by domainName).
Service result:
Correct finalization: 200 OK [{“domainName” : string, “clientId” : string, “topicFilter” : string, “qos” : int, “online” : boolean, [“options” : object]}, …]
Failure: 400 Bad request
Administrative/domain subscribe
Service: POST /subscribe
Message: {“domainName” : string, “clientId” : string, “subscriptions” : [[topic, qos], …], [“options” : object], “tokenId” : string}
Cookie: tokenId
This API needs administration rights (API user must have administrator rights at the destination HUB).
Allows to create a server side subscription at a given MyQttHUB (selected by domainName)
for a particular device (clientId).
subscriptions represent a list of subscriptions to install where each position includes
a list where index 0 includes topic filter and index 1 includes QoS to configured (0,1,2).
// subscriptions example declared in javascript
var subscriptions = [[topic, qos], [topic2, qos2], [topic3, qos3]];
options works as in Subscribe topic.
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Administrative/domain unsubscribe
Service: POST /unsubscribe
Message: {“domainName” : string, “clientId” : string, “subscriptions” : [topic, …], “tokenId” : string}
Cookie: tokenId
This API needs administration rights (API user must have administrator rights at the destination HUB).
Allows to remove a server side subscription at a given MyQttHUB (selected by domainName)
for a particular device (clientId).
subscriptions represent a list of subscriptions to unsubscribe.
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Publish message for a current logged device
Service: POST /publish
Message: {“topic” : string, “qos” : int, “payload” : string, “retain” : boolean, “dup” : boolean, [“props” : object], “tokenId” : string}
Cookie: tokenId
Allows to PUBLISH a message with the provided data. payload is the message to publish encoded in base64: the platform decodes it before sending it to subscribers.
props (optional) carries MQTT v5 message properties. MQTT v5 subscribers receive them; MQTT 3.1.1 subscribers receive the message without them. Only the properties provided are sent (correlationData in base64):
{“payloadFormatIndicator” : 1, “messageExpiryInterval” : 3600, “contentType” : “application/json”, “responseTopic” : “replies/web”, “correlationData” : “cmVxLTE=”, “userProperties” : [{“name” : “site”, “value” : “plant-1”}]}
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Pull messages for a current logged device
Service: POST /pull
Message: {“tokenId” : string}
Cookie: tokenId
Allows to pull (receive) all messages received by the HTTP session (matching its subscriptions) since the last pull.
Service result:
Correct finalization: 200 OK [{“topic” : string, “qos” : int, “payload” : string, “retain” : boolean, “dup” : boolean, “id” : number, [“props” : object]}, …]
Failure: 400 Bad request
-
payloadis encoded in base64. -
ididentifies the message inside the HTTP session: it increases with each message and starts again from 1 with a new login. -
propsreports the MQTT v5 properties of the message, only when it has them.
How messages are kept. Messages wait in a queue that belongs to the HTTP session (the tokenId):
- With this classic pull, messages are removed from the queue when the server handles the request, not when your client receives the response. If the response does not reach your client (connection cut, timeout on your side…), those messages are not delivered again. If you need to control it, use pull with ack.
- Each session keeps up to 10,000 messages waiting to be pulled. If the queue is full, the oldest messages are discarded. Pull frequently enough for your traffic.
- Logout, token expiry or a new login with the same clientId discard the messages not pulled yet.
Pull messages with acknowledgement (pull with ack)
Service: POST /pull
Message: {“tokenId” : string, [“ack” : number], [“limit” : number]}
Cookie: tokenId
Sending ack or limit (or both) enables the pull with acknowledgement for that request. Messages are only removed from the queue once your client confirms them, so a response that does not reach your client does not lose its messages:
-
limit: maximum number of messages reported by the response (1000 when not provided). -
ack: id of the last message your client processed. It confirms that message and every previous one already reported. Confirmed messages are removed from the queue. - Messages reported and not confirmed are reported again by the next pull, with
"dup" : true. A message reported 5 times without being confirmed is discarded.
Service result:
Correct finalization: 200 OK {“messages” : [message, …], “pending” : number, “dropped” : number, “replacedDiscarded” : number}
Failure: 400 Bad request
-
messages: same format as the classic pull, in order byid. -
pending: messages left in the queue after this response. If it is greater than 0, pull again right away. -
dropped: messages discarded since the previous pull, because the queue was full or because they were reported 5 times without being confirmed. -
replacedDiscarded: messages discarded because a previous HTTP session with the same clientId was replaced by this one (a new login) while it had messages to pull.
Recommended loop:
- Pull with a limit:
{"tokenId" : "...", "limit" : 100}. - Process the messages in order. Use
idto discard repeated ones: a message may be reported again ("dup" : true) when the previous response did not reach your client. - In the next pull, confirm the id of the last message processed:
{"tokenId" : "...", "ack" : 1234, "limit" : 100}. - If
pendingis greater than 0, pull again right away. Otherwise, wait your usual interval. - Check
droppedandreplacedDiscarded: values greater than 0 mean messages were discarded before your client could process them (pull more often, confirm what you process and avoid two logins with the same clientId).
Example:
>> curl --cookie “tokenId=0da82260-207e-4e4e-9fc3-d2846d7c54f0” -X POST https://node02.myqtthub.com/pull -d ‘{“tokenId” : “0da82260-207e-4e4e-9fc3-d2846d7c54f0”, “ack” : 6, “limit” : 2}’
Response example:
{“messages”:[{“topic”:“sensors/temp”,“qos”:1,“payload”:“MjEuNQ==”,“retain”:false,“dup”:true,“id”:7},{“topic”:“sensors/temp”,“qos”:1,“payload”:“MjEuNg==”,“retain”:false,“dup”:false,“id”:8}],“pending”:3,“dropped”:0,“replacedDiscarded”:0}
In this example, message 7 was already reported by a previous pull that was not confirmed (dup), and 3 more messages are waiting: pull again confirming id 8.
Notes:
- Ids belong to the HTTP session: after a new login they start again from 1, so do not confirm ids of a previous session.
- Do not mix both modes in the same session: a classic pull (without
ackandlimit) reports and removes every message in the queue, including the ones not confirmed. - The queue belongs to the HTTP session, as in the classic pull: logout, token expiry or a new login with the same clientId discard it (reported by
replacedDiscardedin the new session). If you need messages to be kept beyond the HTTP session, connect using MQTT with QoS 1 and a persistent session (cleanSession = false).
Request/response (MQTT v5) for a current logged device
Service: POST /request
Message: {“topic” : string, “qos” : int, “payload” : string, [“timeout” : int], [“props” : object], “tokenId” : string}
Cookie: tokenId
Publishes a request and waits for its response, using the MQTT v5 request/response pattern, without having to pull:
- The request is published on
topicwithpayload(base64), adding a Response Topic of this HTTP session ($reply/<clientId>/http-api) and a Correlation Data (the one provided insideprops, or a new one). - The service waits up to
timeoutseconds (10 by default, from 1 to 60) for a message published on that Response Topic with the same Correlation Data, and returns it. - The responder is an MQTT v5 device subscribed to
topic: it must publish its answer on the Response Topic it receives, copying the Correlation Data.
Service result:
Correct finalization: 200 OK {“topic” : string, “qos” : int, “payload” : string, “retain” : boolean, “dup” : boolean, [“props” : object]}
No response in time: 504 Gateway Timeout (No response received after N seconds)
Failure: 400 Bad request
Example (asks the device listening on devices/pump-01/cmd for its status):
>> curl --cookie “tokenId=0da82260-207e-4e4e-9fc3-d2846d7c54f0” -X POST https://node02.myqtthub.com/request -d ‘{“topic” : “devices/pump-01/cmd”, “qos” : 1, “payload” : “c3RhdHVz”, “timeout” : 15, “tokenId” : “0da82260-207e-4e4e-9fc3-d2846d7c54f0”}’
Response example:
{“topic”:"$reply/myWebClient/http-api",“qos”:1,“payload”:“b2s=”,“retain”:false,“dup”:false,“props”:{“correlationData”:“N2YxYzVkMmQ=”}}
Responses to requests are reported by this service, not by /pull.
Publish to a domain (for a logged domain admin device)
Service: POST /publish-to
Message: {“topic” : string, “qos” : int, “payload” : string, “retain” : boolean, “dup” : boolean, “domainName” : string, “skipMatching” : boolean, [“clientId” : string], [“props” : object], “tokenId” : string}
Cookie: tokenId
Allows a domain administrator to publish a message (payload in base64) into one of the domains it administers (selected by domainName), as if it was published inside that domain. skipMatching and clientId are reserved for platform administration: send "skipMatching" : false and leave clientId out.
Example:
>> curl --cookie “tokenId=0da82260-207e-4e4e-9fc3-d2846d7c54f0” -X POST https://node02.myqtthub.com/publish-to -d ‘{“topic” : “alerts/all”, “qos” : 1, “payload” : “bWFpbnRlbmFuY2U=”, “retain” : false, “dup” : false, “domainName” : “hub-yourhub”, “skipMatching” : false, “tokenId” : “0da82260-207e-4e4e-9fc3-d2846d7c54f0”}’
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
List filters
Service: POST /filter/rules
Message: {“domainName” : string, “tokenId” : string}
Cookie: tokenId
Allows to list all filter rules that are currently installed in your HUB. domainName represents your unique domain hub name (like hub-username).
Service returns a list of filters, each one represents a json object.
Service result:
Correct finalization: 200 OK [filter, …]
Failure: 400 Bad request
Add filter
Service: POST /filter/add
Message: {“domainName” : string, “label” : string, “prio” : int, “isActive” : boolean, “ruleType” : int, “permission” : int, “filterItems” : [string, …], “clientIds” : [string, …], “stashToList” : [string, …], “tokenId” : string}
Cookie: tokenId
Allows to create a new filter into the destination MyQttHUB (selected by domainName). label and prio configure the filter label and the filter priority, where a high value represents a low priority and a low value a high priority.
Filter rules with priority 0, 10 or 20, run before priority rules with 50,
60 and 70 priority.
permission is an integer that accepts the following values:
| Permission value | Meaning | Description |
|---|---|---|
| 1 | ok-allow | Accept/autorize action configured by this rule |
| 2 | deny-reject | Deny/reject action configured by this rule |
| 3 | dunno | Does not intercept or reject PUBLISH/SUBCRIBE operation but does apply optional operations like stashing |
ruleType is an integer that accepts the following values:
| ruleType value | Meaning | Description |
|---|---|---|
| 1 | limit-subscribe | Accept/rejects SUBCRIBE commands received according to permission and topic filters configured. |
| 2 | limit-publish | Accept/rejects PUBLISH commands received according to permission and topic filters configured. |
| 3 | content-control | Accept/rejects PUBLISH commands received according to permission and content filters configured. |
filterItems is a list of strings: topic filters for limit-subscribe and limit-publish rules, or content filters matched against the PUBLISH payload for content-control rules. In topic filters, %c and %u are replaced by the clientId and the userName of the device.
If filterItems is left empty ([]), it matches all topics and payloads.
clientIds is a list of strings with the clientIds the rule applies to. If clientIds is empty ([]), the rule applies to all clientIds.
stashToList is a list of strings with the stash names where the message is stashed when the rule applies ([] for none).
You can edit this filter rule by POSTing again with new values using same label.
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Remove filter
Service: POST /filter/remove
Message: {“domainName” : string, “label” : string, “tokenId” : string}
Cookie: tokenId
Allows to remove the filter selected by the provided label into the MyQttHUB selected by domainName.
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Stash download
You can program your downloads using available REST HTTP API. There are two services:
- /calculate/stashed/download (service to get download size and quota consuption)
- /stashed/download (service that provides download support)
It is not required to use /calculate/stashed/download. You can directly use /stashed/download to get your stash content and consume quota associated.
Here is how to calculate your stash download (example built using curl; adapt it to your toolchain):
-
(Optional) Login and calculate your download stash:
curl -X POST https://node02.myqtthub.com/login -d ‘{“clientId” : “YourAdminClientId”, “userName” : “YourUsername”, “password” : “aPassword”, “cleanSession” : false }’
{“clientId”:“myQttTestDomainAdmin”,“validUntil”:1549559337,“stamp”:1549386537,“cleanSession”:false,“tokenId”:“b0a7dda4-62e6-4e18-8008-0c780bd67f5e”} -
As response, you get a tokenId for use in next interations:
{“clientId”:“YourAdminClientId”,“validUntil”:1549559337,“stamp”:1549386537,“cleanSession”:false,“tokenId”:“b0a7dda4-62e6-4e18-8008-62e60bd67f5e”}
-
Now calculate your download with:
curl --cookie ‘tokenId=b0a7dda4-62e6-4e18-8008-62e60bd67f5e’ -X POST https://node02.myqtthub.com/calculate/stashed/download -d ‘{“tokenId” : “b0a7dda4-62e6-4e18-8008-62e60bd67f5e”, “domainName” : “your-hub-domain”, “stashName” : “your-stash-name”, “downloadAs” : “csv”, “downloadFrame” : “all”}’
Service information:
API configuration API value Service name /calculate/stashed/download param: domainName your hub domain param: stashName your stash name param: downloadAs Download format. Allowed values are: csv, json, xml param: downloadFrame Configure/limits download period: allowed values (num)h for last (num) hours, (num)days, for last (num) days and “all” to download all. Some valid examples are 24h, 7days, 31days or all -
Previous command will return an indication about download size and quota to be consumed:
{“size”:12110,“qta”:3}
-
Now, you can download using:
curl --cookie ‘tokenId=e734b134-0f05-4405-935c-7a4834c0603c’ -X POST https://node02.myqtthub.com/stashed/download -d ‘{“tokenId” : “e734b134-0f05-4405-935c-7a4834c0603c”, “domainName” : “your-hub-domain”, “stashName” : “your-stash-name”, “downloadAs” : “csv”, “downloadFrame” : “all”}’
Service information:
API configuration API value Service name /stashed/download param: domainName your hub domain param: stashName your stash name param: downloadAs Download format. Allowed values are: csv, json, xml param: downloadFrame Configure/limits download period: allowed values (num)h for last (num) hours, (num)days, for last (num) days and “all” to download all. Some valid examples are 24h, 7days, 31days or all param: includeProps Optional (true/false): also include the MQTT v5 properties of each message -
As a response, given this example, you will get:
topic;qos;payload;retain;dup;clientId;userName;domainName;remoteAddr;stamp;date;operationId
sensors/temp;0;RmlyZSEhISEhIQ==;false;false;unknown-client-id;not-defined;your-hub-domain;not-defined;1545064449699;Mon Dec 17 17:34:09 CET 2018;D9793D5E1AB9092A8E45E1270D1B4975
sensors/temp;0;RmlyZSEhISEh;false;false;unknown-client-id;not-defined;your-hub-domain;not-defined;1545064393948;Mon Dec 17 17:33:13 CET 2018;9C7A930B1CF19C35556CBAE59448CAC6
message/test;0;RmlyZSEhISE=;false;false;unknown-client-id;not-defined;your-hub-domain;not-defined;1544807149647;Fri Dec 14 18:05:49 CET 2018;E1C0C230793678A78D35E5E66E0D606C
message/test;0;RmlyZSEhISEh;false;false;unknown-client-id;not-defined;your-hub-domain;not-defined;1544807061914;Fri Dec 14 18:04:21 CET 2018;B13243E2E7646E60A19312F05B24EC46
All the stash services below need domain administration rights for the domain provided.
List stashes
Service: POST /stashes
Message: {“domainName” : string, “tokenId” : string}
Cookie: tokenId
Returns the stashes of the domain.
Service result:
Correct finalization: 200 OK [{“name” : string, [“description” : string], “domainName” : string, “msgRotationCount” : number, “msgRotationSize” : number, “skipStashing” : boolean, “msgCount” : number, “quota” : number}, …]
Failure: 400 Bad request
msgCount is the number of messages stored and quota the storage they use.
View a stash
Service: POST /stash/view
Message: {“domainName” : string, “stashName” : string, “tokenId” : string}
Cookie: tokenId
Returns a list with the stash selected by stashName (same format as List stashes).
Add or update a stash
Service: POST /stash/add
Message: {“name” : string, [“description” : string], “domainName” : string, “msgRotationCount” : int, “msgRotationSize” : int, “skipStashing” : boolean, “tokenId” : string}
Cookie: tokenId
Creates a stash, or updates it when a stash with that name already exists. Messages are stored in a stash by the filter rules that name it in stashToList (see Create filter).
-
msgRotationCountandmsgRotationSize: maximum number of messages and maximum total size (bytes) kept by the stash; the oldest messages are rotated out (-1 for no limit). -
skipStashing: reserved, sendfalse.
Example:
>> curl --cookie “tokenId=0da82260-207e-4e4e-9fc3-d2846d7c54f0” -X POST https://node02.myqtthub.com/stash/add -d ‘{“name” : “sensors”, “description” : “Sensor readings”, “domainName” : “hub-yourhub”, “msgRotationCount” : 10000, “msgRotationSize” : -1, “skipStashing” : false, “tokenId” : “0da82260-207e-4e4e-9fc3-d2846d7c54f0”}’
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Remove a stash
Service: POST /stash/remove
Message: {“name” : string, “domainName” : string, “tokenId” : string}
Cookie: tokenId
Removes the stash and all its messages.
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Get stashed messages
Service: POST /stashed
Message: {“domainName” : string, “stashName” : string, “downloadFrame” : string, “tokenId” : string}
Cookie: tokenId
Returns the messages of the stash for the period given by downloadFrame (same values as in Stash download: 24h, 7days, all…). For big stashes, use Stash download.
Service result:
Correct finalization: 200 OK [{“topic” : string, “qos” : int, “payload” : string, “retain” : boolean, “dup” : boolean, “clientId” : string, “userName” : string, “domainName” : string, “remoteAddr” : string, “stamp” : number, “date” : string, “idOperation” : string, [“props” : object]}, …]
Failure: 400 Bad request
stamp (milliseconds) identifies each message inside the stash: it is used to remove or replay it.
Clear stashed messages
Service: POST /stashed/clear
Message: {“domainName” : string, “stashName” : string, “keepFrame” : string, “tokenId” : string}
Cookie: tokenId
Removes the messages of the stash older than the period given by keepFrame (24h, 7days…). With "all", removes every message. The stash itself is kept.
Example (keeps the messages of the last 7 days):
>> curl --cookie “tokenId=0da82260-207e-4e4e-9fc3-d2846d7c54f0” -X POST https://node02.myqtthub.com/stashed/clear -d ‘{“domainName” : “hub-yourhub”, “stashName” : “sensors”, “keepFrame” : “7days”, “tokenId” : “0da82260-207e-4e4e-9fc3-d2846d7c54f0”}’
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Remove or replay a stashed message
Service: POST /stashed/message/remove
Service: POST /stashed/message/replay
Message: {“domainName” : string, “stashName” : string, “stamp” : number, “tokenId” : string}
Cookie: tokenId
The message is selected by its stamp (see Get stashed messages):
- /stashed/message/remove removes it from the stash.
- /stashed/message/replay publishes it again in the domain, so current subscribers receive it (it is not stored again in the stash).
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Get domain security settings
Service: POST /domain/security/get
Message: {“domain” : string, “tokenId” : string}
Cookie: tokenId
Returns the security settings of the domain (note the field is domain, not domainName). Needs domain administration rights for that domain.
Service result:
Correct finalization: 200 OK {“domainName” : string, “aclDefaultDeny” : boolean, “authMethods” : [string, …], “requireLoginIpAllowlist” : boolean, “requireScram” : boolean, [“maxSessionExpiry” : number], “injectIdentity” : boolean, “audit” : boolean, “alertMail” : boolean, [“alertTopic” : string], “alertAclPerMinute” : number, “clientMsgsPerSecond” : number, “clientMsgsPerMinute” : number, “clientMaxMessageSize” : number, “ipMaxConnections” : number, “ipConnectsPerMinute” : number}
Failure: 400 Bad request
The meaning of each setting is described in Change domain security settings. clientMsgsPerSecond, clientMsgsPerMinute, clientMaxMessageSize, ipMaxConnections and ipConnectsPerMinute are limits per connection and per source address (0 means no limit).
Change domain security settings
Service: POST /domain/security/set
Message: {“domain” : string, [“aclDefaultDeny” : boolean], [“authMethods” : [string, …]], [“requireLoginIpAllowlist” : boolean], [“requireScram” : boolean], [“maxSessionExpiry” : number], [“injectIdentity” : boolean], [“audit” : boolean], [“alertMail” : boolean], [“alertTopic” : string], [“alertAclPerMinute” : int], “tokenId” : string}
Cookie: tokenId
Changes the settings provided; the ones left out keep their current value. Needs domain administration rights for that domain. Changes apply to new connections.
-
aclDefaultDeny: SUBSCRIBE and PUBLISH are denied when no filter rule applies (instead of accepted). -
authMethods: login methods accepted for MQTT connections of the domain:classic(clientId + userName + password),scram(MQTT v5 enhanced authentication),admin,sci(clientId only) andbootstrap. All by default. It does not apply to the login of this API. -
requireLoginIpAllowlist: MQTT connections of devices without allowed IPs (see List allowed ips) are refused. -
requireScram: MQTT connections are only accepted using SCRAM (MQTT v5). -
maxSessionExpiry: maximum MQTT v5 Session Expiry Interval (seconds) of the domain sessions; -1 removes the limit. -
injectIdentity: MQTT v5 messages published in the domain carry the verified identity of the sender as User Properties. -
audit: security events of the domain (logins, ACL denials, takeovers, quotas…) are recorded. -
alertMail,alertTopic,alertAclPerMinute: alerts on events that may reveal a stolen credential, sent by mail to the domain administrators and/or published onalertTopic(""removes it). They needauditenabled.
Example (deny by default and accept only classic and SCRAM logins):
>> curl --cookie “tokenId=0da82260-207e-4e4e-9fc3-d2846d7c54f0” -X POST https://node02.myqtthub.com/domain/security/set -d ‘{“domain” : “hub-yourhub”, “aclDefaultDeny” : true, “authMethods” : [“classic”, “scram”], “tokenId” : “0da82260-207e-4e4e-9fc3-d2846d7c54f0”}’
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
SCRAM status of the devices of a domain
Service: POST /scram/status
Message: {“domainName” : string, “tokenId” : string}
Cookie: tokenId
Returns, for each device of the domain, the SCRAM mechanisms for which it has credentials. Devices get SCRAM credentials when their password is set or changed, or when they log in with their password. A device without mechanisms cannot log in using SCRAM yet. Needs domain administration rights.
Service result:
Correct finalization: 200 OK [{“clientId” : string, [“userName” : string], “mechanisms” : [string, …]}, …]
Failure: 400 Bad request
Response example:
[{“clientId”:“sensor-01”,“userName”:“sensors”,“mechanisms”:[“SCRAM-SHA-1”,“SCRAM-SHA-256”]},{“clientId”:“old-device”,“userName”:“legacy”,“mechanisms”:[]}]