NAV Navbar
shell
  • Introduction
  • Authentication
  • Instance
  • Users
  • ACL
  • Formats
  • Status Codes
  • 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://customer.cloudmqtt_api.com/api/user
    

    Instance

    Restart

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

    HTTP Request

    POST https://customer.cloudmqtt_api.com/api/instance/restart

    Users

    List users

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

    The above command returns JSON structured like this:

    [
      {
        "username":"test"
      }
    ]
    

    HTTP Request

    GET https://customer.cloudmqtt_api.com/api/user

    Get user info

    curl -u :apikey \
      https://customer.cloudmqtt_api.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://customer.cloudmqtt_api.com/api/user/<USERNAME>

    URL Parameters

    Parameter Description
    USERNAME Username 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://customer.cloudmqtt_api.com/api/user
    

    HTTP Request

    POST https://customer.cloudmqtt_api.com/api/user

    Request Parameters

    Parameter Description
    username Username for the new user
    password Password for the new user

    Update user password

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

    HTTP Request

    PUT https://customer.cloudmqtt_api.com/api/user/<USERNAME>

    URL Parameters

    Parameter Description
    USERNAME The user to update

    Request Parameters

    Parameter Description
    password New password for the user

    Delete user

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

    HTTP Request

    DELETE https://customer.cloudmqtt_api.com/api/user/<USERNAME>

    URL Parameters

    Parameter Description
    USERNAME The user to delete

    ACL

    List ACL rules

    curl -u :apikey \
      https://customer.cloudmqtt_api.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.

    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://customer.cloudmqtt_api.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://customer.cloudmqtt_api.com/api/acl
    

    HTTP Request

    POST https://customer.cloudmqtt_api.com/api/acl

    Request Parameters

    Parameter Description
    type Which type of ACL rule to create
    username Which user the rule applies to
    pattern Pattern for which topics to match
    read Allow reads
    write Allow writes

    Delete ACL Rule

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

    HTTP Request

    DELETE https://customer.cloudmqtt_api.com/api/acl

    Request Parameters

    Parameter Description
    username Delete rules for this user
    topic Delete 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 Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The kitten requested is hidden for administrators only.
    404 Not Found -- The specified kitten could not be found.
    405 Method Not Allowed -- You tried to access a kitten with an invalid method.
    500 Internal Server Error -- We had a problem with our server. Try again later.