# Account and sub-user endpoints

> Create PacketStream reseller sub-users, transfer balances, retrieve 90 days of usage, inspect accounts, and reset proxy auth keys.

All endpoints use the base URL `https://reseller.packetstream.io` and require the reseller bearer token.

## Endpoint summary

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/reseller/my_info` | Retrieve the reseller account |
| `POST` | `/reseller/sub_users/create` | Create a sub-user |
| `GET` | `/reseller/sub_users/view_all` | List all owned sub-users |
| `POST` | `/reseller/sub_users/view_single` | Retrieve one owned sub-user |
| `POST` | `/reseller/sub_users/view_txs` | Retrieve 90 days of daily usage |
| `POST` | `/reseller/sub_users/reset_auth_key` | Replace a sub-user's proxy auth key |
| `POST` | `/reseller/sub_users/give_balance` | Move balance from reseller to sub-user |
| `POST` | `/reseller/sub_users/take_balance` | Return balance from sub-user to reseller |

## Sub-user object

Account and sub-user endpoints return this public shape inside `data`:

```json
{
  "username": "u_7c091a1328f6caae",
  "balance": 500,
  "proxy_authkey": "REDACTED_PROXY_AUTH_KEY",
  "date_created": "2026-07-22T14:05:00Z"
}
```

`balance` is measured in USD cents. The `proxy_authkey` is a proxy credential, not the Reseller API bearer token.

## Retrieve the reseller account

```text
GET /reseller/my_info
```

```bash
curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${PACKETSTREAM_RESELLER_TOKEN}" \
  'https://reseller.packetstream.io/reseller/my_info' \
  | jq '.data'
```

## Create a sub-user

```text
POST /reseller/sub_users/create
```

Once an authenticated request has enough reseller balance to attempt creation, the $0.10 fee is charged even when validation fails or the username already exists. Generate and validate a unique random username before calling the endpoint.

Usernames:

- are globally unique across PacketStream;
- are converted to lowercase;
- must contain 4–32 letters, numbers, periods, or underscores;
- cannot begin or end with a period or underscore;
- cannot contain adjacent periods or underscores.

This generates an allowed random username without using end-customer personal data:

```bash
SUBUSER="u_$(openssl rand -hex 8)"
```

Create it:

```bash
curl --silent --show-error --fail-with-body \
  --request POST \
  --header "Authorization: Bearer ${PACKETSTREAM_RESELLER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data "$(jq -nc --arg username "${SUBUSER}" '{username: $username}')" \
  'https://reseller.packetstream.io/reseller/sub_users/create' \
  | jq
```

The new sub-user starts with zero balance. The successful response contains its username and proxy auth key.

## List all sub-users

```text
GET /reseller/sub_users/view_all
```

```bash
curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${PACKETSTREAM_RESELLER_TOKEN}" \
  'https://reseller.packetstream.io/reseller/sub_users/view_all' \
  | jq '.data'
```

Do not depend on the returned array order.

## Retrieve one sub-user

```text
POST /reseller/sub_users/view_single
```

Request body:

```json
{"username":"u_7c091a1328f6caae"}
```

The username must belong to the authenticated reseller.

## Transfer balance to a sub-user

```text
POST /reseller/sub_users/give_balance
```

```json
{
  "username": "u_7c091a1328f6caae",
  "amount_usd_cents": 500
}
```

The amount must be a positive integer of at least one cent and cannot exceed the reseller's available balance. A successful response reports the sub-user's new balance.

## Return balance to the reseller

```text
POST /reseller/sub_users/take_balance
```

```json
{
  "username": "u_7c091a1328f6caae",
  "amount_usd_cents": 100
}
```

The amount must be a positive integer of at least one cent and cannot exceed the sub-user's available balance. The amount is returned to the reseller account.

## Retrieve bandwidth history

```text
POST /reseller/sub_users/view_txs
```

Request body:

```json
{"username":"u_7c091a1328f6caae"}
```

The response contains up to the most recent 90 days of usage grouped by UTC day:

```json
[
  {
    "bandwidth": {
      "up": 16814,
      "down": 142086
    },
    "timestamp": "2026-07-21T00:00:00Z"
  }
]
```

`up` and `down` are measured in bytes. Do not depend on array order; sort records by `timestamp` in your application.

## Reset a proxy auth key

```text
POST /reseller/sub_users/reset_auth_key
```

Request body:

```json
{"username":"u_7c091a1328f6caae"}
```

The response contains the replacement `proxy_authkey`. Update your secret store and branded customer configuration as one controlled operation, and treat the previous proxy credential as retired.

## Connect a sub-user

Provide the sub-user's `username` and `proxy_authkey` with the branded proxy hostname established during reseller onboarding. Sub-users support the same [country targeting](https://packetstream.io/docs/country-targeting/) and [rotation or sticky-session behavior](https://packetstream.io/docs/rotation-sticky-sessions/) available through PacketStream's proxy network.

Keep the Reseller API bearer token in your server-side control plane. Never expose it to sub-users or use it as a proxy password.