# 子账号

子账号是代理网关的访问控制单元。每个代理请求都必须引用一个子账号，且每个子账号有独立的密码、限额、产品范围。

## 端点

| 方法       | 路径                               | 用途         |
| -------- | -------------------------------- | ---------- |
| `GET`    | `/subusers`                      | 列出全部子账号    |
| `POST`   | `/subusers`                      | 创建子账号      |
| `GET`    | `/subusers/{id}`                 | 获取单个       |
| `PATCH`  | `/subusers/{id}`                 | 更新名称、限额、状态 |
| `POST`   | `/subusers/{id}/rotate-password` | 轮换密码       |
| `DELETE` | `/subusers/{id}`                 | 删除（不可恢复）   |

## 列出

```bash
curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/subusers?product=residential
```

响应：

```json
{
  "data": [
    {
      "id":              "sub_01HX2K3PQ4M5",
      "name":            "s1a2b3c4d5e",
      "label":           "acme-prod",
      "products":        ["residential", "mobile"],
      "status":          "active",
      "concurrent_max":  600,
      "rps_max":         1000,
      "created_at":      "2026-05-01T00:00:00Z"
    }
  ],
  "next_cursor": null
}
```

筛选参数：`product=residential|mobile|isp`、`status=active|disabled`、`label_contains=...`。

## 创建

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "label":    "acme-staging",
       "products": ["residential"],
       "concurrent_max": 200,
       "rps_max":        500
     }' \
     https://api.helodata.com/v1/subusers
```

响应：

```json
{
  "id":       "sub_01HX2K3PQ4M5",
  "name":     "s9z8y7x6w5v",
  "password": "Mz4yQv8R...",
  "label":    "acme-staging",
  "products": ["residential"]
}
```

> `password` **仅此一次返回**，请立即保存——我们只存哈希。

### 字段约束

| 字段               | 约束                                     |
| ---------------- | -------------------------------------- |
| `label`          | 1–64 字符，`[a-z0-9-]`                    |
| `products`       | `["residential", "mobile", "isp"]` 的子集 |
| `concurrent_max` | 1–10000，不可超过套餐上限                       |
| `rps_max`        | 1–10000                                |

## 获取单个

```bash
curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/subusers/sub_01HX2K3PQ4M5
```

## 更新

```bash
curl -X PATCH -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"concurrent_max": 1000, "status": "active"}' \
     https://api.helodata.com/v1/subusers/sub_01HX2K3PQ4M5
```

可编辑：`label`、`status`（`active` / `disabled`）、`concurrent_max`、`rps_max`。要改 `products` 请删除后重建。

把 `status` 改为 `disabled` 后所有代理请求立即返回 `403`，凭证仍在但已停用。

## 轮换密码

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/subusers/sub_01HX2K3PQ4M5/rotate-password
```

响应包含新密码（仅此一次）。旧密码继续 60 秒有效，之后返回 `407`。

## 删除

```bash
curl -X DELETE -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/subusers/sub_01HX2K3PQ4M5
```

删除子账号。进行中的代理请求最多需要 60 秒收尾。

## 错误

| 状态码   | code                | 含义                      |
| ----- | ------------------- | ----------------------- |
| `409` | `label_taken`       | 已有子账号使用该 label          |
| `422` | `over_plan_limit`   | `concurrent_max` 超过套餐上限 |
| `404` | `subuser_not_found` | ID 错误                   |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/api-can-kao/sub-users.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.