EMQX REST API认证

EMQX 服务启动后，您可以访问 http://localhost:18083/api-docs/index.html 来查看 API 的文档。还可以直接在 Swagger UI 上尝试执行一些 API。默认情况下，Dashboard 配置下的 swagger_support 设置为 true，表示启用 Swagger UI 支持，即开启所有 swagger 相关的功能，例如生成交互式 API 文档。您也可以将它设置为 false 以禁用此功能。

基本路径

EMQX 在 REST API 上做了版本控制，EMQX 5.0.0 以后的所有 API 调用均以 /api/v5 开头。

HTTP 请求头

除非有特殊说明，绝大多数 API 要求请求头中 Accept 值设置为 application/json，响应内容将以 JSON 格式返回。

HTTP 响应状态码

EMQX 遵循 HTTP 响应状态码标准，可能的状态码如下：

认证

EMQX 的 REST API 支持两种主要的认证方法：使用 API 密钥的基本认证和 Bearer Token 认证。

使用 API 密钥的基本认证

在这种方法中，您通过使用 API 密钥和密钥作为用户名和密码来对 API 请求进行身份验证。EMQX 的 REST API 基于 HTTP 基本认证框架，要求提供这些凭据。使用 EMQX REST API 之前，您需要先创建一个 API 密钥。

创建 API 密钥

您可以在 Dashboard 系统设置 -> API 密钥 页面中手动创建用于认证的 API 密钥，详细操作请参考 Dashboard - API 密钥。

认证方式

使用生成的 API Key 以及 Secret Key 分别作为 Basic 认证的用户名与密码，官方示例如下：

import okhttp3.*;

import java.io.IOException;

public class EMQXNodesAPIExample {
    public static void main(String[] args) {
        try {
            String username = "4f33d24d7b8e448d";
            String password = "gwtbmFJZrnzUu8mPK1BxUkBA66PygETiDEegkf1q8dD";

            OkHttpClient client = new OkHttpClient();

            Request request = new Request.Builder()
                    .url("http://localhost:18083/api/v5/nodes")
                    .header("Content-Type", "application/json")
                    .header("Authorization", Credentials.basic(username, password))
                    .build();

            Response response = client.newCall(request).execute();
            System.out.println(response.body().string());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

例如：

ApiKey:a972505196446799
SecretKey:mn9AhnqtVDpSoloAJ29CThsl9AimB5TYpBJrxoZ9AsT8atH
Base64(a972505196446799:mn9AhnqtVDpSoloAJ29CThsl9AimB5TYpBJrxoZ9AsT8atH)得到
=> YTk3MjUwNTE5NjQ0Njc5OTptbjlBaG5xdFZEcFNvbG9BSjI5Q1Roc2w5QWltQjVUWXBCSnJ4b1o5QXNUOGF0SA==
在其开头补充 Basic + 一个空格
=> Basic YTk3MjUwNTE5NjQ0Njc5OTptbjlBaG5xdFZEcFNvbG9BSjI5Q1Roc2w5QWltQjVUWXBCSnJ4b1o5QXNUOGF0SA==

使用 Basic Token 认证

注意：并不是所有接口都可以使用该认证，有些接口会报401。

使用 Bearer Token 认证

除了基于 API 密钥的身份验证外，您还可以使用 Bearer Token 来实现对 EMQX REST API 的安全和程序化访问。要获取 Bearer Token，请按照以下说明向登录 API 端点发送请求。

获取 Bearer Token

要请求 Bearer Token，请向以下登录 API 端点发送 HTTP POST 请求：

POST http://your-emqx-address:8483/api/v5/login

请求头：

Content-Type: application/json

请求体：

{
  "username": "admin",
  "password": "yourpassword"
}

postman演示：

使用 Bearer Token 进行身份认证

获取 Bearer Token 后，将其包含在您的 API 请求的 Authorization 标头中，如下所示：

--header "Authorization: Bearer <your-token>"

接口调用演示：

EMQX官方文档：https://docs.emqx.com/zh/emqx/latest/admin/api.html#java