The API and API Tokens
Create API tokens, understand their product and supplier scope, and use the versioned HTTP API to manage sub-users, generate endpoints and read usage.
Last updated
The dashboard is for humans; the API is for your pipelines. Anything you manage by hand, from creating sub-users to generating proxy configuration, you can also drive from code with an API token.
Creating a token
Open API Access in the dashboard sidebar, above Settings. The page has two tabs: API Tokens, which lists your account's tokens and lets you create a new one, and API Reference, which renders the live OpenAPI document with per-endpoint code samples and a request runner.
- Give the token a name so you can tell your tokens apart later.
- Choose its scope: the product and supplier pairs it may use.
- Press Create token.
The token value is shown once. Copy it immediately. It is stored only as a hash, so it cannot be retrieved again. If you lose it, revoke it and create a replacement.
An account can hold up to five tokens, the same ceiling as its sub-users.
Scope
A token is not an account key with full access. Each token carries an explicit set of (product, supplier) pairs, for example residential on one supplier and mobile on another. Within those pairs it can do everything operational: manage every user, reset proxy passwords, set allocations, and generate configuration.
Two boundaries are worth stating plainly:
- No billing. A token can never buy traffic, create a checkout, change a plan or read invoices. Spending stays a dashboard action.
- No token management. A token cannot create or revoke other tokens. That surface requires a signed-in dashboard user, so a leaked token can never extend its own reach.
Authenticating
Send the token as a Bearer credential on every request.
curl https://lightningbytes.com/api/v1/me \
-H "Authorization: Bearer sk-lb_your_token"
A request with a missing, revoked or expired token receives 401. A request outside the token's scope receives 403 with a scope_denied code.
The endpoints
Every route lives under /api/v1. Where a token is scoped to one supplier for a product, you may omit supplier; where it spans several, name the one you mean.
| Method and path | What it does |
|---|---|
GET /me | Your token's identity and effective scope |
GET /products | In-scope products with balance and usage |
GET /suppliers | In-scope suppliers with their products and capabilities |
GET /locations | Targeting options (countries) for a product |
GET /users | List sub-users |
POST /users | Create a sub-user with one or more services |
GET /users/{id} | One sub-user |
DELETE /users/{id} | Delete a sub-user and release its credentials |
POST /users/{id}/password | Reset a sub-user's proxy password |
POST /users/{id}/enable | Enable a service grant |
POST /users/{id}/disable | Disable a service grant |
PATCH /users/{id}/allocation | Set a sub-user's traffic allocation |
GET /users/{id}/endpoints | Generate proxy configuration |
POST /users/{id}/endpoints/rotate | Regenerate configuration with fresh session ids |
POST /proxy-check | Check an endpoint's connectivity and exit IP |
GET /usage/overview | Balance and usage per product |
GET /usage/traffic | Period traffic bytes |
GET /usage/traffic/history | Traffic time series |
GET /usage/requests/history | Request-count series |
GET /usage/breakdown | Share of traffic by user and by country |
GET /usage/users | Per-sub-user traffic for the period |
Generating an endpoint
Requesting configuration for a sub-user returns credentials and wire parts. Omit session_id to get a fresh exit IP per row, or pass one to pin a sticky session.
curl "https://lightningbytes.com/api/v1/users/USER_ID/endpoints?product=residential&protocol=socks5&country=us&count=3" \
-H "Authorization: Bearer sk-lb_your_token"
Targeting is validated against what the route actually supports. An unsupported parameter is a 400, never a silently dropped one.
The OpenAPI specification
The machine-readable contract is served at /api/v1/openapi.json. Point a client generator or a request tool at it to explore the surface.
The same document is rendered as an interactive reference in the dashboard, on the API Reference tab of API Access. It shows every endpoint with code samples in several languages and its own authentication panel, so you can paste a token and run a request without leaving the page. To open the reference directly, link to /dashboard/api?tab=api-reference.
Revoking a token
Revoke a token from the API Access page's API Tokens tab with the row's Revoke action. Revocation is immediate: any request using that token fails with 401.