# Authentication and response handling

> Authenticate to the PacketStream Reseller API with a bearer token and handle its JSON response envelope and failures safely.

The Reseller API uses one bearer token to authorize account and sub-user management. This token is different from the proxy auth keys returned for the reseller and its sub-users.

## Send the bearer token

Include the token in the `Authorization` header on every API request:

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

An absent, malformed, or unknown token produces an unauthorized response.

## Protect the token

Treat the token as a secret with authority over reseller funds and sub-user credentials.

- Store it in a secret manager or protected environment variable.
- Never place it in client-side code, a mobile application, or software distributed to end customers.
- Redact the `Authorization` header from logs, traces, screenshots, and support messages.
- Use separate application permissions around operations that transfer balance or reset credentials.
- Rotate the token on the dashboard's Reseller API page if it may have been exposed. The new token is shown once.

A new token can take up to five minutes to start working across the Reseller API service, and the previous token stops working within the same window. Do not rotate it again while waiting.

## JSON requests

POST endpoints accept a JSON request body. Send an explicit content type:

```bash
curl --silent --show-error --fail-with-body \
  --request POST \
  --header "Authorization: Bearer ${PACKETSTREAM_RESELLER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"username":"u_example1234"}' \
  'https://reseller.packetstream.io/reseller/sub_users/view_single'
```

Amounts use integer USD cents. For example, `500` represents $5.00.

## Response envelope

Every response uses the same top-level JSON shape:

```json
{
  "status": 200,
  "message": "",
  "timestamp": 1784739600,
  "data": {}
}
```

| Field | Meaning |
| --- | --- |
| `status` | HTTP status represented as an integer |
| `message` | Human-readable warning or failure information; commonly empty on success |
| `timestamp` | Response time as Unix seconds |
| `data` | Endpoint-specific object, array, or `null` |

Check the actual HTTP status before reading `data`. Do not automate recovery by matching the exact wording of `message`; use it for diagnostics.

## Retry mutating requests carefully

The API does not accept an idempotency key. If a connection ends before your application receives a response, a POST operation may already have completed.

Before retrying:

1. query the relevant account or sub-user;
2. determine whether the intended state change is already visible;
3. retry only when repeating the operation is safe;
4. keep attempts and total retry time bounded.

This matters especially for sub-user creation because every invocation costs $0.10, including attempts that fail validation or collide with an existing username.

Continue with the [complete endpoint reference](https://packetstream.io/docs/reseller-api/endpoints/).