API
EMQX Cloud API 遵循 RESTful 定义，为您提供编程访问 EMQX Cloud 中管理部署的能力。通过 API，您可以对认证、客户端、主题等进行管理，并可以获取到更多的指标信息。
API 具有以下特征：
- JSON 格式：所有响应内容均以 JSON 格式呈现。
- 仅支持 HTTPS：您只能通过 HTTPS 访问 API，确保所有通过网络发送的数据都使用 TLS 加密。
- 基于密钥的访问和摘要认证。在访问 EMQX Cloud API 之前，您必须生成 API 密钥。所有请求都通过 HTTP 摘要认证进行身份验证，并确保 API 密钥永远不会通过网络发送。
如何调用 API
您可以在部署详情页面下的 API 访问中，获取到 API 访问地址。
认证鉴权
HTTP API 使用 Basic 认证 方式，id 和 password 须分别填写 AppID 和 AppSecret。 您可以在部署详情页面下的 API 访问中，通过创建应用访问来添加和删除 AppID/AppSecret。
构造请求
请求地址由以下几个部分组成：
{API}/{resource-path}?{query-string}
响应码
HTTP 状态码 (status codes)
接口在调用成功时总是返回 200 OK，响应内容则以 JSON 格式返回。
可能的状态码如下：
| 状态码 | 描述 |
|---|---|
| 200 | 成功，返回的 JSON 数据将提供更多信息 |
| 400 | 客户端请求无效，例如请求体或参数错误 |
| 401 | 客户端未通过服务端认证，使用无效的身份验证凭据可能会发生 |
| 404 | 找不到请求的路径或者请求的对象不存在 |
| 500 | 服务端处理请求时发生内部错误 |
返回码 (result codes)
接口的响应消息体为 JSON 格式，其中总是包含返回码 code。
可能的返回码如下：
| 返回码 | 描述 |
|---|---|
| 0 | 成功 |
| 101 | RPC 错误 |
| 102 | 未知错误 |
| 103 | 用户名或密码错误 |
| 104 | 空用户名或密码 |
| 105 | 用户不存在 |
| 106 | 管理员账户不可删除 |
| 107 | 关键请求参数缺失 |
| 108 | 请求参数错误 |
| 109 | 请求参数不是合法 JSON 格式 |
| 110 | 插件已开启 |
| 111 | 插件已关闭 |
| 112 | 客户端不在线 |
| 113 | 用户已存在 |
| 114 | 旧密码错误 |
| 115 | 不合法的主题 |
API 版本说明
基于 EMQX Cloud 使用的 EMQX 内核版本的不同，API 也分为基于 EMQX 4.x 和 EMQX 5.x 版本。请选择您开通的部署类型对应的 API 版本。