The API and API Tokens
Create API tokens, understand their product and pool 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 & MCP 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 pool 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. Support can raise that limit on request, and it raises the sub-user limit too.
Scope
A token is not an account key with full access. Each token carries an explicit set of (product, pool) pairs, for example residential on one pool and mobile on another. Within those pairs it can do everything operational: manage every user, reset proxy passwords, set allocations, and generate configuration.
A pool is a source of exit IPs for a product. Today every product is served by a single pool, so a pair usually reads as just the product; the pool dimension exists because a product may be served by more than one pool. The pair selects which pool's addresses an endpoint uses.
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. A token whose account is on hold receives 403 with account_on_hold.
The endpoints
Every route lives under /api/v1. Where a token is scoped to one pool for a product, you may omit pool; 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 /pools | In-scope pools with their products and capabilities |
GET /locations | Countries a pool supports for a product |
GET /locations/{country}/regions | Regions of a country the pool supports |
GET /locations/{country}/regions/{region}/cities | Cities of a region the pool supports, paged |
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 pool actually supports. An unsupported parameter or place is a 400 unsupported_targeting, never a silently dropped one. country is a two-letter code, region is a region code such as US.OH (any case), city is a numeric city id, and session_id is 1 to 32 letters and digits. state is still accepted as a deprecated alias of region; use region in new code. A region must belong to the country, and a city to the country and, when given, the region.
Find valid values with the location routes. Every location route takes product and pool and lists only what that pool serves, so two pools can return different lists, and a pool that is not yours or does not serve the product is a 400 invalid_pool. Regions come back as codes with a name and a placeholder flag, and cities as an id and a name. A region with placeholder: true (named Other) bundles the places the pool does not group by region: it is the only region of a country the pool serves countrywide, and otherwise it comes last and appears only when some cities need it. Pass its code as region like any other. The cities route takes limit (at most 500), offset and a q filter, so large regions are read a page at a time.
curl "https://lightningbytes.com/api/v1/locations/us/regions/US.OH/cities?product=residential&q=col&limit=20" \
-H "Authorization: Bearer sk-lb_your_token"
Then pass the id you want:
curl "https://lightningbytes.com/api/v1/users/USER_ID/endpoints?product=residential&country=us®ion=US.OH&city=4509177" \
-H "Authorization: Bearer sk-lb_your_token"
Usage periods
The usage routes take an optional start_at and end_at. Each is an ISO-8601 date or date-time, at most 40 characters; a date-time with no offset is read as UTC. The period is rounded out to whole hours and may span at most 100 days. An empty value, or leaving the parameter out, uses the default period.
Errors
Every error has the same body: { "error": { "code": "...", "message": "..." } }. Branch on code; the message is for people and may change.
| Status and code | Meaning |
|---|---|
400 bad_request | A parameter is missing or out of range |
400 unsupported_targeting | The pool does not support a targeting parameter or place you sent; the message points to the location routes |
400 invalid_pool, 400 ambiguous_pool | The pool does not serve that product, or the token holds several pools for it and none was named |
400 insufficient_balance | The allocation is larger than the remaining balance can back |
401 unauthorized | Missing, revoked or expired token |
403 scope_denied | Outside the token's product and pool scope |
403 account_on_hold | The account is on hold; contact support@lightningbytes.com |
503 locations_unavailable | The location list could not be read; retry shortly. A request with no location is unaffected |
404 not_found | No such sub-user on your account |
409 not_provisioned | The sub-user has no active proxy for that product yet; retry shortly |
429 rate_limited | Too many requests or too many proxy checks at once; retry after a short wait |
502 pool_error | The pool could not complete the request; retry shortly |
503 service_unavailable, 503 pool_unavailable | Temporarily unavailable; retry shortly |
The OpenAPI document lists the codes on its Error schema.
Connecting an MCP client
The same token you created above also authenticates an MCP server, so an agent can manage the account directly instead of calling each HTTP endpoint itself. Send the token as a bearer credential to the endpoint below.
https://www.lightningbytes.com/api/mcp
Use the www host exactly as written. The apex (lightningbytes.com) redirects to www, and an HTTP client drops the Authorization header when a redirect changes the host, so an apex URL fails with 401 even though the token is valid.
For Claude Code, one command adds it:
claude mcp add --transport http lightningbytes \
https://www.lightningbytes.com/api/mcp \
--header "Authorization: Bearer sk-lb_your_token"
For any other client, the MCP tab of API & MCP has a copy-ready block per client. The client you pick decides one field: Roo Code and Zoo Code require an explicit "type": "streamable-http" on a URL entry and will not load one without it, Cursor infers the transport from the url, VS Code names it "http", and Claude Desktop's local config file accepts only stdio servers, so its block bridges the endpoint through mcp-remote. See Using the MCP Server for the full table and the failure symptoms.
The MCP server exposes the same operational actions as the HTTP API: reading products, pools, locations and usage; listing, creating and deleting sub-users; resetting a proxy password; enabling, disabling and allocating a sub-user; generating and rotating endpoints; and checking a proxy. A separate tool returns the dashboard link for adding traffic, which is where a human completes a purchase.
Note
Important
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 & MCP. 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 & MCP page's API Tokens tab with the row's Revoke action. Revocation is immediate: any request using that token fails with 401.