子账号

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

端点

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

列出

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

响应：

{
  "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=...。

创建

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

响应：

{
  "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

获取单个

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

更新

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，凭证仍在但已停用。

轮换密码

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

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

删除

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 错误