Sub-users

The sub-users endpoints let you create and manage sub-users programmatically: their proxy credentials, their traffic limits, and resetting their recorded usage. This is the API equivalent of managing sub-users in the dashboard. All requests go to https://api.nodemaven.com/api/v2/base/ and carry the header Authorization: x-api-key YOUR_API_KEY. See the NodeMaven API overview for the shared basics.

Endpoints

Method	Path	What it does	Request body	Responses
`GET`	`/sub-users/`	Retrieve a list of all sub-users		200, 400, 404, 500
`POST`	`/sub-users/`	Create a new sub-user	`SubUserCreateRequest`	200, 400, 403, 500
`PUT`	`/sub-users/`	Update an existing sub-user’s details	`SubUserUpdateRequest`	200, 400, 403, 404, 500
`DELETE`	`/sub-users/`	Delete a specific sub-user by ID		204, 400, 404, 500
`POST`	`/sub-users/reset/usage`	Reset sub-users traffic usage	`SubUserResetUsageRequest`	200, 400, 404, 500

Creating a sub-user

SubUserCreateRequest:

Field	Type	Required	Constraints
`proxy_username`	string	Yes	Minimum 9, maximum 100 characters. Pattern `^[a-zA-Z0-9_]*$`
`proxy_password`	string	Yes	Minimum 9, maximum 100 characters. Pattern `^[a-zA-Z0-9_]*$`
`is_traffic_limited`	boolean	No	Defaults to `false`
`traffic_limit`	integer	No	In bytes

The 9-character minimum applies to both the username and the password. An 8-character username is rejected. Only letters, digits and underscores are allowed in either field.

curl -X POST https://api.nodemaven.com/api/v2/base/sub-users/ \
  -H "Authorization: x-api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_username": "USERNAME",
    "proxy_password": "PASSWORD",
    "is_traffic_limited": true,
    "traffic_limit": 10737418240
  }'

Traffic limits are in bytes, not GB

traffic_limit, used_traffic and traffic_limit_increment_bytes are all measured in bytes. Sending 10 does not mean 10 GB. It means 10 bytes. To save you the arithmetic:

Limit you want	Binary GB (1024³)	Decimal GB (1000³)
1 GB	`1073741824`	`1000000000`
5 GB	`5368709120`	`5000000000`
10 GB	`10737418240`	`10000000000`
50 GB	`53687091200`	`50000000000`
100 GB	`107374182400`	`100000000000`

A binary gigabyte is 1024³ bytes and a decimal gigabyte is 1000³ bytes.

Updating a sub-user

SubUserUpdateRequest:

Field	Type	Required	Notes
`id`	uuid	Yes	Which sub-user to update
`proxy_username`	string	No	Maximum 100 characters
`proxy_password`	string	No	Maximum 100 characters
`is_traffic_limited`	boolean	No	Nullable
`traffic_limit`	integer	No	Nullable. In bytes. Sets the limit to an absolute value
`used_traffic`	integer	No	In bytes
`traffic_limit_increment_bytes`	integer	No	Nullable. Signed delta applied to the current traffic limit in bytes: positive adds, negative subtracts

traffic_limit and traffic_limit_increment_bytes are mutually exclusive. Send one or the other, never both in the same request. Use traffic_limit when you know the absolute figure you want, and traffic_limit_increment_bytes when you want to top up or claw back relative to whatever the limit is now.

For example, to raise a sub-user’s limit without needing to know what it currently is, send a positive traffic_limit_increment_bytes and omit traffic_limit entirely. To claw some back, send a negative value. Use the byte figures from the table above.

Deleting a sub-user

DELETE /sub-users/ takes the sub-user’s id as a query parameter, not in a body. The id is a uuid and it is required.

curl -X DELETE "https://api.nodemaven.com/api/v2/base/sub-users/?id=SUB_USER_ID" \
  -H "Authorization: x-api-key YOUR_API_KEY"

A successful delete returns 204, so no body comes back.

You cannot delete your own main account through this endpoint. Passing the main account’s ID returns a 400 with You can't delete your main user. The endpoint only removes sub-users.

Three things return a 400:

Cause	Error returned
The sub-user feature is not enabled on the account	`You don't have permission to create sub users`
No `id` supplied	`ID parameter is required`
The ID is the main account	`You can't delete your main user`

A 404 means there is no sub-user with that ID.

Resetting usage

SubUserResetUsageRequest takes one field:

Field	Type	Required	Notes
`ids`	array of uuid	Yes	The sub-users whose usage should be reset

Because ids is an array, one call resets several sub-users at once. You do not need to loop.

curl -X POST https://api.nodemaven.com/api/v2/base/sub-users/reset/usage \
  -H "Authorization: x-api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["SUB_USER_ID_1", "SUB_USER_ID_2"]
  }'

Sub-users covers what sub-users are for and how to manage them in the dashboard.

Platform API

Product APIs

Endpoints

Creating a sub-user

Traffic limits are in bytes, not GB

Updating a sub-user

Deleting a sub-user

Resetting usage

​Endpoints

​Creating a sub-user

​Traffic limits are in bytes, not GB

​Updating a sub-user

​Deleting a sub-user

​Resetting usage

​Related reading

Endpoints

Creating a sub-user

Traffic limits are in bytes, not GB

Updating a sub-user

Deleting a sub-user

Resetting usage

Related reading