# REST API

The REST API allows you to query MQTT clients, sessions, subscriptions, and routes. You can also query and monitor the metrics and statistics of the broker.

# Base URL

All REST APIs in the documentation have the following base URL:

http(s)://host:8080/api/v2/

# Basic Authentication

The HTTP requests to the REST API are protected with HTTP Basic authentication, For example:

curl -v --basic -u <user>:<passwd> -k http://localhost:8080/api/v2/nodes/emq@127.0.0.1/clients

# Nodes

# List all Nodes in the Cluster

Definition:

GET api/v2/management/nodes

Example Request:

GET api/v2/management/nodes

Response:

{
    "code": 0,
    "result": [
        {
            "name": "emq@127.0.0.1",
            "version": "2.3.10",
            "sysdescr": "Erlang MQTT Broker",
            "uptime": "3 minutes, 32 seconds",
            "datetime": "2018-06-29 09:03:52",
            "otp_release": "R20/9.3.3",
            "node_status": "Running"
        }
    ]
}

# Retrieve a Node's Info

Definition:

GET api/v2/management/nodes/{node_name}

Example Request:

GET api/v2/management/nodes/emq@127.0.0.1

Response:

{
    "code": 0,
    "result": {
        "version": "2.3.10",
        "sysdescr": "Erlang MQTT Broker",
        "uptime": "5 minutes, 12 seconds",
        "datetime": "2018-06-29 09:05:32",
        "otp_release": "R20/9.3.3",
        "node_status": "Running"
    }
}

# List all Nodes'statistics in the Cluster

Definition:

GET api/v2/monitoring/nodes

Example Request:

GET api/v2/monitoring/nodes

Response:

{
    "code": 0,
    "result": [
        {
            "name": "emq@127.0.0.1",
            "otp_release": "R20/9.3.3",
            "memory_total": "72.94M",
            "memory_used": "50.55M",
            "process_available": 262144,
            "process_used": 324,
            "max_fds": 7168,
            "clients": 0,
            "node_status": "Running",
            "load1": "1.65",
            "load5": "1.93",
            "load15": "2.01"
        }
    ]
}

Retrieve a node's statistics ---------------------------

Definition:

GET api/v2/monitoring/nodes/{node_name}

Example Request:

GET api/v2/monitoring/nodes/emq@127.0.0.1

Response:

{
    "code": 0,
    "result": {
        "name": "emq@127.0.0.1",
        "otp_release": "R20/9.3.3",
        "memory_total": "73.69M",
        "memory_used": "50.12M",
        "process_available": 262144,
        "process_used": 324,
        "max_fds": 7168,
        "clients": 0,
        "node_status": "Running",
        "load1": "1.88",
        "load5": "1.99",
        "load15": "2.02"
    }
}

# Clients

# List all Clients on a Node

Definition:

GET api/v2/nodes/{node_name}/clients

Request Parameter:

curr_page={page_no}&page_size={page_size}

Example Request:

api/v2/nodes/emq@127.0.0.1/clients?curr_page=1&page_size=20

Response:

{
    "code": 0,
    "result": {
        "current_page": 1,
        "page_size": 20,
        "total_num": 1,
        "total_page": 1,
        "objects": [
            {
                "client_id": "mqttjs_722b4d845f",
                "username": "undefined",
                "ipaddress": "127.0.0.1",
                "port": 58459,
                "clean_sess": true,
                "proto_ver": 4,
                "keepalive": 60,
                "connected_at": "2018-06-29 09:15:25"
            }
        ]
    }
}

Retrieve a Client on a Node --------------------------

Definition:

GET api/v2/nodes/{node_name}/clients/{client_id}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/clients/mqttjs_722b4d845f

Response:

{
    "code": 0,
    "result": {
        "objects": [
            {
                "client_id": "mqttjs_722b4d845f",
                "username": "undefined",
                "ipaddress": "127.0.0.1",
                "port": 58459,
                "clean_sess": true,
                "proto_ver": 4,
                "keepalive": 60,
                "connected_at": "2018-06-29 09:15:25"
            }
        ]
    }
}

Retrieve a Client in the Cluster -------------------------------

Definition:

GET api/v2/clients/{client_id}

Example Request:

GET api/v2/clients/mqttjs_722b4d845f

Response:

{
    "code": 0,
    "result": {
        "objects": [
            {
                "client_id": "mqttjs_722b4d845f",
                "username": "undefined",
                "ipaddress": "127.0.0.1",
                "port": 58459,
                "clean_sess": true,
                "proto_ver": 4,
                "keepalive": 60,
                "connected_at": "2018-06-29 09:15:25"
            }
        ]
    }
}

# Disconnect a Specified Client in the Cluster

Definition:

DELETE api/v2/clients/{clientid}

Example Request:

DELETE api/v2/clients/mqttjs_722b4d845f

Response:

{
    "code": 0,
    "result": []
}

# Clear the ACL of a Specified Client in the Cluster

Definition:

PUT api/v2/clients/{clientid}/clean_acl_cache

Request Parameter:

{
    "topic": "test"
}

Request Example:

PUT api/v2/clients/C_1492145414740/clean_acl_cache

Request Json Parameter:
{
    "topic": "test"
}

Response:

{
    "code": 0,
    "result": []
}

# Sessions

# List all Sessions on a Node

Definition:

GET api/v2/node/{node_name}/sessions

Request Parameter:

curr_page={page_no}&page_size={page_size}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/sessions?curr_page=1&page_size=20

Response:

{
    "code": 0,
    "result": {
        "current_page": 1,
        "page_size": 20,
        "total_num": 1,
        "total_page": 1,
        "objects": [
            {
                "client_id": "mqttjs_722b4d845f",
                "clean_sess": true,
                "subscriptions": 0,
                "max_inflight": 32,
                "inflight_len": 0,
                "mqueue_len": 0,
                "mqueue_dropped": 0,
                "awaiting_rel_len": 0,
                "deliver_msg": 0,
                "enqueue_msg": 0,
                "created_at": "2018-06-29 10:05:13"
            }
        ]
    }
}

# Retrieve a Session on a Node

Definition:

GET api/v2/nodes/{node_name}/sessions/{client_id}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/sessions/mqttjs_722b4d845f

Response:

{
    "code": 0,
    "result": {
        "objects": [
            {
                "client_id": "mqttjs_722b4d845f",
                "clean_sess": true,
                "subscriptions": 0,
                "max_inflight": 32,
                "inflight_len": 0,
                "mqueue_len": 0,
                "mqueue_dropped": 0,
                "awaiting_rel_len": 0,
                "deliver_msg": 0,
                "enqueue_msg": 0,
                "created_at": "2018-06-29 10:05:13"
            }
        ]
    }
}

Retrieve a Session in the Cluster --------------------------------

Definition:

GET api/v2/sessions/{client_id}

Example Request:

GET api/v2/sessions/mqttjs_722b4d845f

Response:

{
    "code": 0,
    "result": {
        "objects": [
            {
                "client_id": "mqttjs_722b4d845f",
                "clean_sess": true,
                "subscriptions": 0,
                "max_inflight": 32,
                "inflight_len": 0,
                "mqueue_len": 0,
                "mqueue_dropped": 0,
                "awaiting_rel_len": 0,
                "deliver_msg": 0,
                "enqueue_msg": 0,
                "created_at": "2018-06-29 10:05:13"
            }
        ]
    }
}

# Subscriptions

# List all Subscriptions of a Node

Definition:

GET api/v2/nodes/{node_name}/subscriptions

Request parameters:

curr_page={page_no}&page_size={page_size}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/subscriptions?curr_page=1&page_size=20

Response:

{
    "code": 0,
    "result": {
        "current_page": 1,
        "page_size": 20,
        "total_num": 1,
        "total_page": 1,
        "objects": [
            {
                "client_id": "mqttjs_722b4d845f",
                "topic": "/World",
                "qos": 0
            }
        ]
    }
}

List Subscriptions of a Client on a node ------------------------------

Definition:

GET api/v2/nodes/{node_name}/subscriptions/{clientid}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/subscriptions/mqttjs_722b4d845f

Response:

{
    "code": 0,
    "result": {
        "objects": [
            {
                "client_id": "mqttjs_722b4d845f",
                "topic": "/World",
                "qos": 0
            }
        ]
    }
}

# List Subscriptions of a Client in cluster

Definition:

GET api/v2/subscriptions/{clientid}

Example Request:

GET api/v2/subscriptions/mqttjs_722b4d845f

Response:

{
    "code": 0,
    "result": {
        "objects": [
            {
                "client_id": "mqttjs_722b4d845f",
                "topic": "/World",
                "qos": 0
            }
        ]
    }
}

# Routes

# List all Routes in the Cluster

Definition:

GET api/v2/routes

Request parameters:

curr_page={page_no}&page_size={page_size}

Example Request:

GET api/v2/routes?curr_page=1&page_size=20

Response:

{
    "code": 0,
    "result": {
        "current_page": 1,
        "page_size": 20,
        "total_num": 1,
        "total_page": 1,
        "objects": [
            {
                "topic": "/World",
                "node": "emq@127.0.0.1"
            }
        ]
    }
}

Retrieve a Route of Topic in the Cluster -------------------------------

Definition:

GET api/v2/routes/{topic}

Example Request:

GET api/v2/routes//World

Response:

{
    "code": 0,
    "result": {
        "objects": [
            {
                "topic": "/World",
                "node": "emq@127.0.0.1"
            }
        ]
    }
}

# Publish/Subscribe

# Publish Message

Definition:

POST api/v2/mqtt/publish

Request parameters:

{
    "topic" : "/World",
    "payload": "hello",
    "qos": 0,
    "retain" : false,
    "client_id": "mqttjs_722b4d845f"
}

Tip

The topic parameter is required, other parameters are optional. Payload defaults to empty string, qos defaults to 0, retain defaults to false, client_id defaults to 'http'.

Example Request:

POST api/v2/mqtt/publish

Request Json Parameter:
{
      "topic" : "/World",
    "payload": "hello",
      "qos": 0,
      "retain" : false,
      "client_id": "mqttjs_722b4d845f"
}

Response:

{
    "code": 0,
    "result": []
}

# Create a Subscription

Definition:

POST api/v2/mqtt/subscribe

Request parameters:

{
    "topic": "/World",
    "qos": 0,
    "client_id": "mqttjs_722b4d845f"
}

Example Request:

POST api/v2/mqtt/subscribe
Request Json Parameter:
{
      "topic" : "/World",
      "qos": 0,
      "client_id": "mqttjs_722b4d845f"
}

Response:

{
    "code": 0,
    "result": []
}

Unsubscribe Topic ------------

Definition:

POST api/v2/mqtt/unsubscribe

Request Parameter:

{
      "topic" : "/World",
      "client_id": "mqttjs_722b4d845f"
}

Example Request:

POST api/v2/mqtt/unsubscribe
Request Json Parameter:
{
      "topic" : "/World",
      "client_id": "mqttjs_722b4d845f"
}

Response:

{
    "code": 0,
    "result": []
}

# Plugins

# List all Plugins of a Node

Definition:

GET /api/v2/nodes/{node_name}/plugins/

Example Request:

GET api/v2/nodes/emq@127.0.0.1/plugins

Response:

{
    "code": 0,
    "result": [
        {
            "name": "emq_auth_clientid",
            "version": "2.3.10",
            "description": "Authentication with ClientId/Password",
            "active": false
        },
        {
            "name": "emq_auth_http",
            "version": "2.3.10",
            "description": "Authentication/ACL with HTTP API",
            "active": false
        },
        {
            "name": "emq_auth_jwt",
            "version": "2.3.10",
            "description": "Authentication with JWT",
            "active": false
        },
        {
            "name": "emq_auth_ldap",
            "version": "2.3.10",
            "description": "Authentication/ACL with LDAP",
            "active": false
        },
        {
            "name": "emq_auth_mongo",
            "version": "2.3.10",
            "description": "Authentication/ACL with MongoDB",
            "active": false
        },
        {
            "name": "emq_auth_mysql",
            "version": "2.3.10",
            "description": "Authentication/ACL with MySQL",
            "active": false
        },
        {
            "name": "emq_auth_pgsql",
            "version": "2.3.10",
            "description": "Authentication/ACL with PostgreSQL",
            "active": false
        },
        {
            "name": "emq_auth_redis",
            "version": "2.3.10",
            "description": "Authentication/ACL with Redis",
            "active": false
        },
        {
            "name": "emq_auth_username",
            "version": "2.3.10",
            "description": "Authentication with Username/Password",
            "active": false
        },
        {
            "name": "emq_coap",
            "version": "2.3.10",
            "description": "CoAP Gateway",
            "active": false
        },
        {
            "name": "emq_dashboard",
            "version": "2.3.10",
            "description": "EMQ Web Dashboard",
            "active": true
        },
        {
            "name": "emq_lua_hook",
            "version": "2.3.10",
            "description": "EMQ Hooks in lua",
            "active": false
        },
        {
            "name": "emq_modules",
            "version": "2.3.10",
            "description": "EMQ Modules",
            "active": true
        },
        {
            "name": "emq_plugin_template",
            "version": "2.3.10",
            "description": "EMQ Plugin Template",
            "active": false
        },
        {
            "name": "emq_recon",
            "version": "2.3.10",
            "description": "Recon Plugin",
            "active": true
        },
        {
            "name": "emq_reloader",
            "version": "2.3.10",
            "description": "Reloader Plugin",
            "active": false
        },
        {
            "name": "emq_retainer",
            "version": "2.3.10",
            "description": "EMQ Retainer",
            "active": true
        },
        {
            "name": "emq_sn",
            "version": "2.3.10",
            "description": "MQTT-SN Gateway",
            "active": false
        },
        {
            "name": "emq_stomp",
            "version": "2.3.10",
            "description": "Stomp Protocol Plugin",
            "active": false
        },
        {
            "name": "emq_web_hook",
            "version": "2.3.10",
            "description": "EMQ Webhook Plugin",
            "active": false
        }
    ]
}

# Start/Stop a Plugin

Definition:

PUT /api/v2/nodes/{node_name}/plugins/{name}

Request parameters:

{
    "active": true/false,
}

Example Request:

PUT api/v2/nodes/emq@127.0.0.1/plugins/emq_recon
Request Json Parameter:
{
    "active": true
}

Response:

{
    "code": 0,
    "result": []
}

# List all Listeners

Definition:

GET api/v2/monitoring/listeners

Response:

{
    "code": 0,
    "result": {
        "emq@127.0.0.1": [
            {
                "protocol": "dashboard:http",
                "listen": "18083",
                "acceptors": 2,
                "max_clients": 512,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:tcp",
                "listen": "127.0.0.1:11883",
                "acceptors": 16,
                "max_clients": 102400,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:tcp",
                "listen": "0.0.0.0:1883",
                "acceptors": 16,
                "max_clients": 102400,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:ws",
                "listen": "8083",
                "acceptors": 4,
                "max_clients": 64,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:ssl",
                "listen": "8883",
                "acceptors": 16,
                "max_clients": 1024,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:wss",
                "listen": "8084",
                "acceptors": 4,
                "max_clients": 64,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:api",
                "listen": "127.0.0.1:8080",
                "acceptors": 4,
                "max_clients": 64,
                "current_clients": 1,
                "shutdown_count": []
            }
        ]
    }
}

# List listeners of a Node

Definition:

GET api/v2/monitoring/listeners/{node_name}

Example Request:

GET api/v2/monitoring/listeners/emq@127.0.0.1

Response:

{
    "code": 0,
    "result": [
        {
            "protocol": "mqtt:api",
            "listen": "127.0.0.1:8080",
            "acceptors": 4,
            "max_clients": 64,
            "current_clients": 1,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:wss",
            "listen": "8084",
            "acceptors": 4,
            "max_clients": 64,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:ssl",
            "listen": "8883",
            "acceptors": 16,
            "max_clients": 1024,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:ws",
            "listen": "8083",
            "acceptors": 4,
            "max_clients": 64,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:tcp",
            "listen": "0.0.0.0:1883",
            "acceptors": 16,
            "max_clients": 102400,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:tcp",
            "listen": "127.0.0.1:11883",
            "acceptors": 16,
            "max_clients": 102400,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "dashboard:http",
            "listen": "18083",
            "acceptors": 2,
            "max_clients": 512,
            "current_clients": 0,
            "shutdown_count": []
        }
    ]
}

-------------------------------------Statistics of packet sent and received -------------------------------------

# Get Statistics of all Nodes

Definition:

GET api/v2/monitoring/metrics/

Response:

{
    "code": 0,
    "result": {
        "packets/disconnect":0,
        "messages/dropped":0,
        "messages/qos2/received":0,
        "packets/suback":0,
        "packets/pubcomp/received":0,
        "packets/unsuback":0,
        "packets/pingresp":0,
        "packets/puback/missed":0,
        "packets/pingreq":0,
        "messages/retained":3,
        "packets/sent":0,
        "messages/qos2/dropped":0,
        "packets/unsubscribe":0,
        "packets/pubrec/missed":0,
        "packets/connack":0,
        "packets/pubrec/sent":0,
        "packets/publish/received":0,
        "packets/pubcomp/sent":0,
        "bytes/received":0,
        "packets/connect":0,
        "packets/puback/received":0,
        "messages/sent":0,
        "packets/publish/sent":0,
        "bytes/sent":0,
        "packets/pubrel/missed":0,
        "packets/puback/sent":0,
        "messages/qos0/received":0,
        "packets/subscribe":0,
        "packets/pubrel/sent":0,
        "messages/qos2/sent":0,
        "packets/received":0,
        "packets/pubrel/received":0,
        "messages/qos1/received":0,
        "messages/qos1/sent":0,
        "packets/pubrec/received":0,
        "packets/pubcomp/missed":0,
        "messages/qos0/sent":0
    }
}

Get Statistics of specified Node ------------------------

Definition:

GET api/v2/monitoring/metrics/{node_name}

Example Request:

GET api/v2/monitoring/metrics/emq@127.0.0.1

Response:

{
    "code": 0,
    "result": {
        "packets/disconnect":0,
        "messages/dropped":0,
        "messages/qos2/received":0,
        "packets/suback":0,
        "packets/pubcomp/received":0,
        "packets/unsuback":0,
        "packets/pingresp":0,
        "packets/puback/missed":0,
        "packets/pingreq":0,
        "messages/retained":3,
        "packets/sent":0,
        "messages/qos2/dropped":0,
        "packets/unsubscribe":0,
        "packets/pubrec/missed":0,
        "packets/connack":0,
        "messages/received":0,
        "packets/pubrec/sent":0,
        "packets/publish/received":0,
        "packets/pubcomp/sent":0,
        "bytes/received":0,
        "packets/connect":0,
        "packets/puback/received":0,
        "messages/sent":0,
        "packets/publish/sent":0,
        "bytes/sent":0,
        "packets/pubrel/missed":0,
        "packets/puback/sent":0,
        "messages/qos0/received":0,
        "packets/subscribe":0,
        "packets/pubrel/sent":0,
        "messages/qos2/sent":0,
        "packets/received":0,
        "packets/pubrel/received":0,
        "messages/qos1/received":0,
        "messages/qos1/sent":0,
        "packets/pubrec/received":0,
        "packets/pubcomp/missed":0,
        "messages/qos0/sent":0
    }
}

# Statistics of connected session

# Get Statistics of connected session in all nodes

Definition:

GET api/v2/monitoring/stats

Example Request:

GET api/v2/monitoring/stats

Response:

{
    "code": 0,
    "result": [
        {
            "emq@127.0.0.1": {
                "clients/count": 0,
                "clients/max": 0,
                "retained/count": 3,
                "retained/max": 3,
                "routes/count": 0,
                "routes/max": 0,
                "sessions/count": 0,
                "sessions/max": 0,
                "subscribers/count": 0,
                "subscribers/max": 0,
                "subscriptions/count": 0,
                "subscriptions/max": 0,
                "topics/count": 0,
                "topics/max": 0
            }
        }
    ]
}

# Get Statistics of connected session on specified node

Definition:

GET api/v2/monitoring/stats/{node_name}

Example Request:

GET api/v2/monitoring/stats/emq@127.0.0.1

Response:

{
  "code": 0,
  "result": {
    "clients/count": 0,
    "clients/max": 0,
    "retained/count": 3,
    "retained/max": 3,
    "routes/count": 0,
    "routes/max": 0,
    "sessions/count": 0,
    "sessions/max": 0,
    "subscribers/count": 0,
    "subscribers/max": 0,
    "subscriptions/count": 0,
    "subscriptions/max": 0,
    "topics/count": 0,
    "topics/max": 0
  }
}

# Hot configuration

# Get Modifiable configuration items of all nodes

Definition:

GET api/v2/configs

Example Request:

GET api/v2/configs

Response:

{
    "code": 0,
    "result": {
        "emq@127.0.0.1": [
            {
                "key": "log.console.level",
                "value": "error",
                "datatpye": "enum",
                "app": "emqttd"
            },
            {
                "key": "mqtt.acl_file",
                "value": "etc/acl.conf",
                "datatpye": "string",
                "app": "emqttd"
            },
            {
                "key": "mqtt.acl_nomatch",
                "value": "allow",
                "datatpye": "enum",
                "app": "emqttd"
            },
            {
                "key": "mqtt.allow_anonymous",
                "value": "true",
                "datatpye": "enum",
                "app": "emqttd"
            },
            {
                "key": "mqtt.broker.sys_interval",
                "value": "60",
                "datatpye": "integer",
                "app": "emqttd"
            },
            {
                "key": "mqtt.cache_acl",
                "value": "true",
                "datatpye": "enum",
                "app": "emqttd"
            }
        ]
    }
}

# Get Modifiable configuration items of specified node

Definition:

GET api/v2/nodes/{node_name}/configs

Example Request:

GET api/v2/nodes/emq@127.0.0.1/configs

Response:

{
    "code": 0,
    "result": [
        {
            "key": "log.console.level",
            "value": "error",
            "datatpye": "enum",
            "app": "emqttd"
        },
        {
            "key": "mqtt.acl_file",
            "value": "etc/acl.conf",
            "datatpye": "string",
            "app": "emqttd"
        },
        {
            "key": "mqtt.acl_nomatch",
            "value": "allow",
            "datatpye": "enum",
            "app": "emqttd"
        },
        {
            "key": "mqtt.allow_anonymous",
            "value": "true",
            "datatpye": "enum",
            "app": "emqttd"
        },
        {
            "key": "mqtt.broker.sys_interval",
            "value": "60",
            "datatpye": "integer",
            "app": "emqttd"
        },
        {
            "key": "mqtt.cache_acl",
            "value": "true",
            "datatpye": "enum",
            "app": "emqttd"
        }
    ]
}

# Modify configuration items of all nodes

Definition:

PUT /api/v2/configs/{app_name}

Request Parameter:

{
    "key"   : "mqtt.allow_anonymous",
    "value" : "false"
}

Example Request:

PUT /api/v2/configs/emqttd

Response:

{
    "code"  : 0,
    "result": []
}

# Modify configuration items of specified node

Definition:

PUT /api/v2/nodes/{node_name}/configs/{app_name}

Request Parameter:

{
    "key"   : "mqtt.allow_anonymous",
    "value" : "false"
}

Response:

{
    "code": 0,
    "result": []
}

# Get configuration items of specified plugin in specified node

Definition:

GET api/v2/nodes/{node_name}/plugin_configs/{plugin_name}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/plugin_configs/emq_auth_http

Response:

{
    "code": 0,
    "result": [
        {
            "key": "auth.http.auth_req",
            "value": "http://127.0.0.1:8080/mqtt/auth",
            "desc": "",
            "required": true
        },
        {
            "key": "auth.http.auth_req.method",
            "value": "post",
            "desc": "",
            "required": true
        },
        {
            "key": "auth.http.auth_req.params",
            "value": "clientid=%c,username=%u,password=%P",
            "desc": "",
            "required": true
        },
        {
            "key": "auth.http.super_req",
            "value": "http://127.0.0.1:8080/mqtt/superuser",
            "desc": "",
            "required": true
        },
        {
            "key": "auth.http.super_req.method",
            "value": "post",
            "desc": "",
            "required": true
        },
        {
            "key": "auth.http.super_req.params",
            "value": "clientid=%c,username=%u",
            "desc": "",
            "required": true
        },
        {
            "key": "auth.http.acl_req",
            "value": "http://127.0.0.1:8080/mqtt/acl",
            "desc": "",
            "required": true
        },
        {
            "key": "auth.http.acl_req.method",
            "value": "get",
            "desc": "",
            "required": true
        },
        {
            "key": "auth.http.acl_req.params",
            "value": "access=%A,username=%u,clientid=%c,ipaddr=%a,topic=%t",
            "desc": "",
            "required": true
        }
    ]
}

# Modify configuration item of specified plugin in specified node

Definition:

PUT api/v2/nodes/{node_name}/plugin_configs/{plugin_name}

Request Parameter:

{
    "auth.http.auth_req.method": "get",
    "auth.http.auth_req": "http://127.0.0.1:8080/mqtt/auth",
    "auth.http.auth_req.params": "clientid=%c,username=%u,password=%P",
    "auth.http.acl_req.method": "get",
    "auth.http.acl_req": "http://127.0.0.1:8080/mqtt/acl",
    "auth.http.acl_req.params": "access=%A,username=%u,clientid=%c,ipaddr=%a,topic=%t",
    "auth.http.super_req.method": "post",
    "auth.http.super_req.params": "clientid=%c,username=%u",
    "auth.http.super_req": "http://127.0.0.1:8080/mqtt/superuser"
}

Example Request:

PUT api/v2/nodes/emq@127.0.0.1/plugin_configs/emq_auth_http

Response:

{
    "code": 0,
    "result": []
}

# User Management

# Retrieve Admin User List

Definition:

GET api/v2/users

Request Example:

GET api/v2/users

Response:

{
    "code": 0,
    "result": [
        {
            "username": "admin",
            "tags": "administrator"
        }
    ]
}

# Add Admin User

Definition:

POST api/v2/users

Request Parameter:

{
    "username": "test_user",
    "password": "password",
    "tags": "user"
}

Request Example:

POST api/v2/users

Response:

{
    "code": 0,
    "result": []
}

# Modify Admin User Information

Definition:

PUT api/v2/users/{username}

Request Parameter:

{
    "tags": "admin"
}

Request Example:

PUT api/v2/users/test_user

Response:

{
    "code": 0,
    "result": []
}

# Delete Admin User

Definition:

DELETE api/v2/users/{username}

Request Parameter:

Request Example:

DELETE api/v2/users/test_user

Response:

{
    "code": 0,
    "result": []
}

# Authenticate Admin User

Definition:

POST api/v2/auth

Request Parameter:

{
    "username": "test_user",
    "password": "password"
}

Request Example:

POST api/v2/auth

Response:

{
    "code": 0,
    "result": []
}

# Modify Admin User Password

Definition:

PUT api/v2/change_pwd/{username}

Request Parameter:

{
    "new_pwd": "newpassword",
    "old_pwd": "password"
}

Request Example:

PUT api/v2/change_pwd/test_user

Response:

{
    "code": 0,
    "result": []
}

# Error Code

CodeComment
0Success
101badrpc
102Unknown error
103Username or password error
104empty username or password
105user does not exist
106admin can not be deleted
107missing request parameter
108request parameter type error
109request parameter is not a json
110plugin has been loaded
111plugin has been unloaded
112User offline
113User exists already
114Wrong old password