> For the complete documentation index, see [llms.txt](https://docs.ipdunar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipdunar.com/zh/api-can-kao/sub-users.md).

# 子账号

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

## 端点

| 方法       | 路径                               | 用途         |
| -------- | -------------------------------- | ---------- |
| `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.ipdunar.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.ipdunar.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.ipdunar.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.ipdunar.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.ipdunar.com/v1/subusers/sub_01HX2K3PQ4M5/rotate-password
```

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

## 删除

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

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

## 错误

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
