Sub-users

Sub-users are the unit of access control on the proxy gateway. Every proxy request must reference one, and each sub-user has its own password, limits, and per-product scope.

Endpoints

Method	Path	Purpose
GET	/subusers	List all sub-users
POST	/subusers	Create a sub-user
GET	/subusers/{id}	Get one sub-user
PATCH	/subusers/{id}	Update name, limits, or status
POST	/subusers/{id}/rotate-password	Rotate the password
DELETE	/subusers/{id}	Delete (irreversible)

List

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

Response:

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

Filter with product=residential|mobile|isp, status=active|disabled, label_contains=....

Create

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

Response:

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

The password is shown only in this response. Store it immediately; we keep only a hash.

Field constraints

Field	Constraint
label	1–64 chars, [a-z0-9-]
products	Subset of ["residential", "mobile", "isp"]
concurrent_max	1–10000, must not exceed plan limit
rps_max	1–10000

Get one

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

Update

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

Editable: label, status (active / disabled), concurrent_max, rps_max. To change products, delete and recreate.

Setting status to disabled makes the sub-user immediately return 403 on every proxy request — the credentials still exist, just deactivated.

Rotate password

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

Response includes the new password (shown once). The old password works for 60 seconds, then 407.

Delete

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

Deletes the sub-user. Existing proxy requests in flight may take up to 60 seconds to drain.

Errors

Status	Code	Meaning
409	label_taken	Another sub-user already has this label
422	over_plan_limit	Requested concurrent_max exceeds your plan
404	subuser_not_found	Wrong ID