CloudMQTT

0
1015

Introduction

Documentation for CloudMQTT API.

Authentication

Authentication is done by sending your API key in the password field in Basic Auth, the username should be kept empty.

curl -u :apikey \
  https://api.cloudmqtt.com/api/user

Instance

Restart

curl -XPOST -u :apikey \
  https://api.cloudmqtt.com/api/instance/restart

HTTP Request

POST https://api.cloudmqtt.com/api/instance/restart

Users

List users

curl -u :apikey \
  https://api.cloudmqtt.com/api/user

The above command returns JSON structured like this:

[
  {
    "username":"test"
  }
]

HTTP Request

GET https://api.cloudmqtt.com/api/user

Get user info

curl -u :apikey \
  https://api.cloudmqtt.com/api/user/test

The above command returns JSON structured like this:

{
  "username":"test",
  "acls": [{
    "topic":"sensor/%u",
    "read":false,
    "write":true
  }]
}

HTTP Request

GET https://api.cloudmqtt.com/api/user/<USERNAME>

URL Parameters

ParameterDescription
USERNAMEUsername of the user to get info about

Create user

curl -u :apikey \
-d '{"username":"test", "password":"super_secret_password"}' \
-H "Content-Type:application/json" https://api.cloudmqtt.com/api/user

HTTP Request

POST https://api.cloudmqtt.com/api/user

Request Parameters

ParameterDescription
usernameUsername for the new user
passwordPassword for the new user

Update user password

curl -XPUT -u :apikey \
-d '{"password":"super_secret_password"}' \
-H "Content-Type:application/json" https://api.cloudmqtt.com/api/user/test

HTTP Request

PUT https://api.cloudmqtt.com/api/user/<USERNAME>

URL Parameters

ParameterDescription
USERNAMEThe user to update

Request Parameters

ParameterDescription
passwordNew password for the user

Delete user

curl -XDELETE -u :apikey \
https://api.cloudmqtt.com/api/user/test

HTTP Request

DELETE https://api.cloudmqtt.com/api/user/<USERNAME>

URL Parameters

ParameterDescription
USERNAMEThe user to delete

ACL

List ACL rules

curl -u :apikey \
  https://api.cloudmqtt.com/api/acl

The above command returns JSON structured like this:

[
  {
    "type":"topic",
    "pattern":"test/users/topic",
    "read":true,
    "write":true,
    "username":"custom-user"
  },
  {
    "type":"pattern",
    "pattern":"sensor/%u/data",
    "read":true,
    "write":true,
    "username":null
  }
]

There are two types of ACL rules, topic and pattern. Topic ACLs is applied to a given user. Pattern ACLs is applied to all users.

  • Use # for multi level wildcard acl.
  • Use + for single level wildcard acl.

Creating and deleting users and ACLs are asyncronous tasks and may take up to a minute. Poll list API to see when ready.

HTTP Request

GET https://api.cloudmqtt.com/api/acl

Create ACL Rule

curl -u :apikey \
-d '{"type": "topic", "username":"test", "pattern": "readonly", "read": true, "write": false}' \
-H "Content-Type:application/json" \
https://api.cloudmqtt.com/api/acl

HTTP Request

POST https://api.cloudmqtt.com/api/acl

Request Parameters

ParameterDescription
typeWhich type of ACL rule to create
usernameWhich user the rule applies to
patternPattern for which topics to match
readAllow reads
writeAllow writes

Delete ACL Rule

curl -XDELETE -u :apikey \
-d '{"username":"test", "topic":"readonly"}'
-H "Content-Type:application/json" \
https://api.cloudmqtt.com/api/acl

HTTP Request

DELETE https://api.cloudmqtt.com/api/acl

Request Parameters

ParameterDescription
usernameDelete rules for this user
topicDelete rules for this topic

Formats

All API end points support form FormData and JSON in the request. You need to format the request accordingly and if you send the request as JSON be sure to add the content type header Content-type: application/json otherwise the server won’t be able to parse your request.

Status Codes

Error CodeMeaning
400Bad Request — Your request is invalid.
401Unauthorized — Your API key is wrong.
403Forbidden — The kitten requested is hidden for administrators only.
404Not Found — The specified kitten could not be found.
405Method Not Allowed — You tried to access a kitten with an invalid method.
500Internal Server Error — We had a problem with our server. Try again later.