> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodemaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-users

> Create, update, delete and reset sub-users. Traffic limits are set in bytes, usernames and passwords have a 9-character minimum, and two limit fields cannot be combined.

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](/proxy-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** |

<Warning>
  **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.
</Warning>

```bash theme={null}
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` |

<Note>
  A binary gigabyte is 1024³ bytes and a decimal gigabyte is 1000³ bytes.
</Note>

## 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 |

<Warning>
  **`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.
</Warning>

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.

```bash theme={null}
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.

<Warning>
  **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.
</Warning>

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.

```bash theme={null}
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"]
  }'
```

## Related reading

* [Sub-users](/residential-mobile/sub-users) covers what sub-users are for and how to manage them in the dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.