Skip to content

Commit 511187b

Browse files
MeggielqkMeggielqk
authored
Merge pull request #2705 from emqx/update-api-doc
update(rest api): Add authentication method in REST API
2 parents cc00415 + f370b9d commit 511187b

File tree

4 files changed

+140
-53
lines changed

4 files changed

+140
-53
lines changed

‎en_US/admin/api.md

+72-26
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,41 @@ The section introduces how to work with EMQX REST API.
1010

1111
EMQX has version control on the REST API, all API paths from EMQX 5.0.0 start with `/api/v5`.
1212

13+
## HTTP Headers
14+
15+
Most API requests require the `Accept` header to be set to `application/json`, and then the response will be returned in JSON format unless otherwise specified.
16+
17+
## HTTP Response Status Code
18+
19+
EMQX follows the [HTTP Response Status Code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) standard. The possible status codes are as follows:
20+
21+
| Codes | Description |
22+
| ----- | ------------------------------------------------------------ |
23+
| 200 | Request successfully, and the returned JSON data will provide more details |
24+
| 201 | Created successfully, and the new object will be returned in the Body |
25+
| 204 | Request successfully. Usually used for delete and update operations, and the returned Body will be empty |
26+
| 400 | Bad Request. Usually request body or parameter error |
27+
| 401 | Unauthorized. API key expires or does not exist. |
28+
| 403 | Forbidden. Check if the object is in use or has dependency constraints. |
29+
| 404 | Not Found. You can refer to the `message` field in the Body to check the reason |
30+
| 409 | Conflict. The object already exists or the number limit is exceeded |
31+
| 500 | Internal Server Error. Check the reason in the Body and logs |
32+
1333
## Authentication
1434

15-
EMQX's REST API uses [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#the_general_http_authentication_framework) with API keys as authentication credentials. Before using the EMQX REST API, you need to create an API key.
35+
EMQX's REST API supports two main methods for authentication: basic Authentication using API keys and bearer token authentication.
36+
37+
### Basic Authentication Using API Keys
38+
39+
In this method, you use API keys and secret keys as the username and password to authenticate your API requests. EMQX's REST API follows [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#the_general_http_authentication_framework), where these credentials are required. Before using the EMQX REST API, you must create an API key.
40+
41+
::: tip Note
42+
43+
For security reasons, starting from EMQX 5.0.0, you cannot use Dashboard user credentials to authenticate REST API requests. Instead, you need to create and use API keys for authentication. Note that role-based API credentials are available only in the EMQX Enterprise edition.
1644

17-
:::tip
18-
For security reasons, from EMQX 5.0.0 onwards, Dashboard users cannot be used for REST API authentication. Role-based API credentials are a feature of the EMQX Enterprise edition.
1945
:::
2046

21-
### Create API Keys
47+
#### Create API Keys
2248

2349
You can manually create API keys for authentication on the Dashboard by navigating to **System** -> **API Key**. For instructions, see [System - API Keys](../dashboard/system.md#api-keys).
2450

@@ -32,9 +58,9 @@ api_key = {
3258

3359
In the specified file, add multiple API keys in the format `{API Key}:{Secret Key}:{?Role}`, separated by new lines:
3460

35-
- API Key: Any string as the key identifier.
36-
- Secret Key: Use a random string as the secret key.
37-
- Role (optional): Specify the key's [role](#roles-and-permissions), applicable only in the Enterprise edition.
61+
- **API Key**: Any string as the key identifier.
62+
- **Secret Key**: Use a random string as the secret key.
63+
- **Role (optional)**: Specify the key's [role](#roles-and-permissions), applicable only in the Enterprise edition.
3864

3965
For example:
4066

@@ -48,17 +74,19 @@ API keys created this way are valid indefinitely.
4874

4975
Each time EMQX starts, it will add the data set in the file to the API key list. If an API key already exists, its Secret Key and Role will be updated.
5076

51-
### Roles and Permissions
77+
#### Roles and Permissions (Enterprise Edition)
5278

53-
In the EMQX Enterprise edition, the REST API implements role-based access control. When creating an API key, you can assign one of the following 3 predefined roles:
79+
In the EMQX Enterprise edition, the REST API implements role-based access control. When creating an API key, you can assign one of the following three predefined roles:
5480

5581
- **Administrator**: This role can access all resources and is the default value if no role is specified. The corresponding role identifier is `administrator`.
5682
- **Viewer**: This role can only view resources and data, corresponding to all GET requests in the REST API. The corresponding role identifier is `viewer`.
5783
- **Publisher**: Designed specifically for MQTT message publishing, this role is limited to accessing APIs related to message publishing. The corresponding role identifier is `publisher`.
5884

59-
### Authentication Method
85+
#### Authentication Method Using API Keys
86+
87+
Once you have your API key and secret key, you can use them to authenticate your requests. The API key is used as the username and the secret key as the password for Basic Authentication.
6088

61-
You can use the generated API Key and Secret Key as the username and password for Basic authentication:
89+
Examples in different languages:
6290

6391
:::: tabs type:card
6492
:::tab cURL
@@ -203,25 +231,43 @@ axios
203231
:::
204232
::::
205233

206-
## HTTP Headers
234+
### Authentication Using Bearer Token
207235

208-
Unless otherwise specified, most API requests require the `Accept` header to be set to `application/json`, and then the response will be returned in JSON format.
236+
As an alternative to API key-based authentication, you can use bearer tokens for secure and programmatic access to the EMQX REST API. To obtain a bearer token, send a request to the login API endpoint as described below.
209237

210-
## HTTP Response Status Code
238+
#### Obtain a Bearer Token
211239

212-
EMQX follows the [HTTP Response Status Code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) standard, and the possible status codes are as follows:
240+
To request a bearer token, make an HTTP `POST` request to the following login API endpoint:
213241

214-
| Codes | Description |
215-
| ----- | ------------------------------------------------------------ |
216-
| 200 | Request successfully, and the returned JSON data will provide more details |
217-
| 201 | Created successfully, and the new object will be returned in the Body |
218-
| 204 | Request successfully. Usually used for delete and update operations, and the returned Body will be empty |
219-
| 400 | Bad Request. Usually request body or parameter error |
220-
| 401 | Unauthorized. API key expires or does not exist. |
221-
| 403 | Forbidden. Check if the object is in use or has dependency constraints. |
222-
| 404 | Not Found. You can refer to the `message` field in the Body to check the reason |
223-
| 409 | Conflict. The object already exists or the number limit is exceeded |
224-
| 500 | Internal Server Error. Check the reason in the Body and logs |
242+
```bash
243+
POST http://your-emqx-address:8483/api/v5/login
244+
```
245+
246+
**Headers:**
247+
248+
- `Content-Type: application/json`
249+
250+
**Request Body:**
251+
252+
```json
253+
{
254+
"username": "admin",
255+
"password": "yourpassword"
256+
}
257+
```
258+
259+
- Replace `your-emqx-address` with the address or IP of your EMQX node.
260+
- Replace `"admin"` and `"yourpassword"` with your EMQX Dashboard credentials.
261+
262+
The response will include the bearer token, which you can use to authenticate API requests.
263+
264+
#### Use Bearer Token for Authentication
265+
266+
Once you have the bearer token, include it in the `Authorization` header of your API requests, like this:
267+
268+
```bash
269+
--header "Authorization: Bearer <your-token>"
270+
```
225271

226272
## Pagination
227273

‎en_US/dashboard/system.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ On the API Keys page, you can generate an API key and secret key for accessing t
3939

4040
1. Click the **+ Create** button on the top right corner of the page to bring up the Create API Key pop-up dialog.
4141

42-
2. On the Create API Key dialog, configure in the detailed information for the API key.
42+
2. On the Create API Key dialog, configure the detailed information for the API key.
4343

4444
- The API key will never expire if the Expire At box is left empty.
4545
- Select a role for API key (optional), applicable only in the Enterprise edition. For more information about roles, see [Roles and Permissions](../admin/api.md#roles-and-permissions).

‎zh_CN/admin/api.md

+66-25
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,39 @@ EMQX 服务启动后，您可以访问 [http://localhost:18083/api-docs/index.ht
1010

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

13+
## HTTP 请求头
14+
15+
除非有特殊说明，绝大多数 API 要求请求头中 `Accept` 值设置为 `application/json`，响应内容将以 JSON 格式返回。
16+
17+
## HTTP 响应状态码
18+
19+
EMQX 遵循 [HTTP 响应状态码](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)标准，可能的状态码如下：
20+
21+
| 状态码 | 描述 |
22+
| ------ | ------------------------------------------------------------ |
23+
| 200 | 请求成功，返回的 JSON 数据将提供更多信息 |
24+
| 201 | 创建成功，新建的对象将在 Body 中返回 |
25+
| 204 | 请求成功，常用于删除与更新操作，Body 不会返回内容 |
26+
| 400 | 请求无效，例如请求体或参数错误 |
27+
| 401 | 未通过服务端认证，API 密钥过期或不存在时可能会发生 |
28+
| 403 | 无权操作，检查操作对象是否正在使用或有依赖约束 |
29+
| 404 | 找不到请求路径或请求的对象不存在，可参照 Body 中的 `message` 字段判断具体原因 |
30+
| 409 | 请求的资源已存在或数量超过限制 |
31+
| 500 | 服务端处理请求时发生内部错误，可通过 Body 返回内容与日志判断具体原因 |
32+
1333
## 认证
1434

15-
EMQX 的 REST API 使用 [HTTP Basic 认证](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Authentication#%E9%80%9A%E7%94%A8%E7%9A%84_http_%E8%AE%A4%E8%AF%81%E6%A1%86%E6%9E%B6) 携带 API 密钥作为认证凭据。在开始使用 EMQX REST API 之前，您需要创建 API 密钥。
35+
EMQX 的 REST API 支持两种主要的认证方法：使用 API 密钥的基本认证和 Bearer Token 认证。
36+
37+
### 使用 API 密钥的基本认证
1638

17-
::: tip
18-
出于安全考虑，从 EMQX 5.0.0 开始 Dashboard 用户无法用于 REST API 认证。
19-
API 凭证区分角色是 EMQX 企业版中的功能。
39+
在这种方法中，您通过使用 API 密钥和密钥作为用户名和密码来对 API 请求进行身份验证。EMQX 的 REST API 基于 HTTP 基本认证框架，要求提供这些凭据。使用 EMQX REST API 之前，您需要先创建一个 API 密钥。
40+
41+
::: tip 注意
42+
出于安全考虑，从 EMQX 5.0.0 开始 Dashboard 用户凭据无法用于 REST API 认证。您需要创建并使用 API 密钥进行认证。请注意，基于角色的 API 凭据仅适用于 EMQX 企业版。
2043
:::
2144

22-
### 创建 API 密钥
45+
#### 创建 API 密钥
2346

2447
您可以在 Dashboard **系统设置** -> **API 密钥** 页面中手动创建用于认证的 API 密钥，详细操作请参考 [Dashboard - API 密钥](../dashboard/system.md#api-密钥)。
2548

@@ -33,9 +56,9 @@ api_key = {
3356

3457
在指定的文件中通过多行分割的 `{API Key}:{Secret Key}:{?Role}` 的格式添加多个 API 密钥：
3558

36-
- API Key：任意字符串作为密钥标识。
37-
- Secret Key：使用随机字符串作为密钥。
38-
- Role （可选）：指定密钥的[角色](#角色与权限)，仅适用于企业版。
59+
- **API Key**：任意字符串作为密钥标识。
60+
- **Secret Key**：使用随机字符串作为密钥。
61+
- **Role （可选）**：指定密钥的[角色](#角色与权限)，仅适用于企业版。
3962

4063
例如：
4164

@@ -49,15 +72,15 @@ foo:3CA92E5F-30AB-41F5-B3E6-8D7E213BE97E:publisher
4972

5073
每次 EMQX 启动时，会将文件中设置的数据将添加到 API 密钥列表中，如果存在相同的 API Key，则将更新其 Secret Key 与 Role。
5174

52-
### 角色与权限
75+
#### 角色与权限
5376

5477
在 EMQX 企业版中，REST API 实现了基于角色的访问控制，API 密钥创建时，可以分配以下3个预定义的角色：
5578

5679
- **管理员**：此角色可以访问所有资源，未指定角色时默认使用此值。对应的角色标识为 `administrator`。
5780
- **查看者**：此角色只能查看资源和数据，对应于 REST API 中的所有 GET 请求。对应的角色标识为 `viewer`。
5881
- **发布者**：专门为 MQTT 消息发布定制，此角色仅限于访问与消息发布相关的 API。对应的角色标识为 `publisher`。
5982

60-
### 认证方式
83+
#### 认证方式
6184

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

@@ -204,25 +227,43 @@ axios
204227
:::
205228
::::
206229

207-
## HTTP 请求头
230+
### 使用 Bearer Token 认证
208231

209-
除非有特殊说明，绝大多数 API 要求请求头中 `Accept` 值设置为 `application/json`，响应内容将以 JSON 格式返回。
232+
除了基于 API 密钥的身份验证外，您还可以使用 Bearer Token 来实现对 EMQX REST API 的安全和程序化访问。要获取 Bearer Token，请按照以下说明向登录 API 端点发送请求。
210233

211-
## HTTP 响应状态码
234+
#### 获取 Bearer Token
212235

213-
EMQX 遵循 [HTTP 响应状态码](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)标准，可能的状态码如下：
236+
要请求 Bearer Token，请向以下登录 API 端点发送 HTTP `POST ` 请求：
214237

215-
| 状态码 | 描述 |
216-
| ------ | ----------------------------------------------------------------------------- |
217-
| 200 | 请求成功，返回的 JSON 数据将提供更多信息 |
218-
| 201 | 创建成功，新建的对象将在 Body 中返回 |
219-
| 204 | 请求成功，常用于删除与更新操作，Body 不会返回内容 |
220-
| 400 | 请求无效，例如请求体或参数错误 |
221-
| 401 | 未通过服务端认证，API 密钥过期或不存在时可能会发生 |
222-
| 403 | 无权操作，检查操作对象是否正在使用或有依赖约束 |
223-
| 404 | 找不到请求路径或请求的对象不存在，可参照 Body 中的 `message` 字段判断具体原因 |
224-
| 409 | 请求的资源已存在或数量超过限制 |
225-
| 500 | 服务端处理请求时发生内部错误，可通过 Body 返回内容与日志判断具体原因 |
238+
```bash
239+
POST http://your-emqx-address:8483/api/v5/login
240+
```
241+
242+
**请求头:**
243+
244+
- `Content-Type: application/json`
245+
246+
**请求体:**
247+
248+
```json
249+
{
250+
"username": "admin",
251+
"password": "yourpassword"
252+
}
253+
```
254+
255+
- 将 `your-emqx-address` 替换为您的 EMQX 节点的地址或 IP。
256+
- 将 `"admin"` 和 `"yourpassword"` 替换为您的 EMQX Dashboard 凭证。
257+
258+
响应中将包含 Bearer Token，您可以使用该 Token 对 API 请求进行身份验证。
259+
260+
#### 使用 Bearer Token 进行身份认证
261+
262+
获取 Bearer Token 后，将其包含在您的 API 请求的 `Authorization` 标头中，如下所示：
263+
264+
```bash
265+
--header "Authorization: Bearer <your-token>"
266+
```
226267

227268
## 分页
228269

‎zh_CN/data-integration/data-bridge-mysql.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ MySQL 数据集成是 EMQX 企业版功能。
66

77
:::
88

9-
[MySQL](https://www.mysql.com/) 是一个广泛使用的关系数据库，具备高度的可靠性和稳定性，能够快速安装和配置使用。MySQL Sink 能够将 MQTT 消息高效地存储至 MySQL 数据库中，同时也支持通过事件触发实时更新或删除 MySQL 中的数据。借助 MySQl 数据集成，用户能够轻松实现消息存储、设备在线状态更新以及设备行为记录等功能，实现灵活的物联网数据存储与设备管理功能。
9+
[MySQL](https://www.mysql.com/) 是一个广泛使用的关系数据库，具备高度的可靠性和稳定性，能够快速安装和配置使用。MySQL Sink 能够将 MQTT 消息高效地存储至 MySQL 数据库中，同时也支持通过事件触发实时更新或删除 MySQL 中的数据。借助 MySQL 数据集成，用户能够轻松实现消息存储、设备在线状态更新以及设备行为记录等功能，实现灵活的物联网数据存储与设备管理功能。
1010

1111
本页详细介绍了 EMQX 与 MySQL 的数据集成并提供了实用的规则和 Sink 创建指导。
1212

0 commit comments

Comments
 (0)