Authentication

Every proxy request is authenticated with an API key and resolved to an org, whose plan then clamps what the request may do.

API keys

Create and manage keys in the dashboard. A key is a single secret — the API key — shown only once at creation. Give each key a name so you can recognize it later; the name is just a label, not part of the credential.

Only a SHA-256 hash of the key is stored, and the key is resolved by that hash on every request (with a short-lived in-memory cache, so the hot path doesn’t hit the database each time).

Sending credentials

Authenticate with standard HTTP proxy auth. The API key is the whole credential — send it as the proxy username, with no password:

curl -x http://YOUR_API_KEY@dev.bytetourist.com:8080 https://example.com

Clients that expose a user:pass proxy field take the key as the user and leave the password blank:

curl -x http://dev.bytetourist.com:8080 -U "YOUR_API_KEY:" https://example.com

Encoding targeting in the username

bytetourist reads targeting params from the username, after the key, as --separated key-value pairs:

YOUR_API_KEY-region-eu-cc-de-iptype-residential-strategy-freshest_ip
└─ api key ─┘└─ region=eu ─┘└ cc=de ┘└ iptype=residential ┘└ strategy ┘

Supported username params:

Param	Meaning
region	Region prefix (hierarchical, e.g. eu, eu.west)
cc	Country code (exact, e.g. de)
iptype	datacenter · residential · mobile
protocol	Required node protocol (e.g. http, socks5)
strategy	Selection strategy (see Strategies)
session	Sticky-session id (see Sessions)
strict	true to fail instead of falling back

This style works with clients that only let you set a proxy user:pass, which is why proxy networks use it.

Header overrides

If you control request headers, send X-Proxy-* headers. They override any username-encoded value, and are all stripped before the request is forwarded:

Header	Equivalent param
X-Proxy-Region	region
X-Proxy-Country	cc
X-Proxy-IPType	iptype
X-Proxy-Protocol	protocol
X-Proxy-Strategy	strategy
X-Proxy-Session	session
X-Proxy-Strict	strict

curl -x http://dev.bytetourist.com:8080 -U "YOUR_API_KEY:" \
  -H "X-Proxy-Country: de" -H "X-Proxy-IPType: residential" \
  https://example.com

Keep keys out of logs

The API key travels in the Proxy-Authorization header. Prefer per-environment keys and rotate them from the dashboard if one leaks.

Errors

• 407 Proxy Authentication Required — missing, invalid, or revoked API key.
• 403 Forbidden — authenticated, but the request violates your plan (e.g. a disallowed region or ip_type).