Skip to main content

​
What is a client identity?

A client identity is a persistent persona that Proxy Hopper attaches to each (IP, target) pair. When enabled, every request made through a given IP to a given target looks like it comes from the same browser — consistent headers, the same cookie jar — across multiple requests. Without identities, every request looks like a cold, new connection with no session history. Many targets flag this as bot-like behaviour. With identities, a request from IP 10.0.0.1 to api.example.com arrives with a consistent User-Agent, Accept headers that match that browser, and any session cookies the target has previously set.

​
What an identity contains

Fingerprint profile — a bundle of HTTP request headers that together resemble a real browser: Cookie jar — a per-identity dictionary of cookies received from the target. Cookies are parsed from Set-Cookie response headers and replayed on subsequent requests through the same IP. Cookies with Max-Age=0 or an expired Expires date are deleted automatically.

​
Built-in fingerprint profiles

Proxy Hopper ships with five browser profiles: Each new identity picks a profile at random. This means different IPs in the same pool present as different browser types — which is more realistic than every IP using the same User-Agent. Profile selection is not configurable per-target. Cookies are stored per identity, not on a shared HTTP session. Proxy Hopper uses a DummyCookieJar on the underlying aiohttp session to prevent automatic cross-IP cookie sharing. Each identity manages its own dict[str, str] cookie store and injects it into outbound requests manually. This means a session cookie issued by the target to IP 10.0.0.1 is never sent on a request made through IP 10.0.0.2.

​
Rotation triggers

An identity is replaced with a fresh one when any of the following occurs: The quarantine rotation fires before the IP returns to the pool, so a fresh identity is ready as soon as the IP becomes available again. When rotateOn429 is true and a 429 is received, the identity rotates even if the IP is not quarantined. The reasoning: a 429 often means the session is rate-limited, not just the IP. A new identity resets that session state.

​
Warmup requests

When a fresh identity is created, it has no cookies. Some targets issue session cookies on first contact that are required for subsequent requests to succeed. The optional warmup request handles this:
When warmup is configured, Proxy Hopper sends a GET to the specified path through the new identity before routing real requests through it. Any cookies issued in the warmup response are stored in the identity and replayed on subsequent requests.

​
Configuration

Identity is configured per-target under the identity: key:
See Config Reference for the complete field reference.

​
When to enable identities

Enable identities when your target:
  • Sets session cookies and expects them to be replayed
  • Rate-limits per session rather than (or in addition to) per IP
  • Returns 429s that persist beyond the minRequestInterval cooldown — suggesting session-level throttling
  • Detects bots by analysing User-Agent consistency or the absence of Accept headers
For simple targets that are rate-limited only by IP, identities add overhead with no benefit. Leave them disabled.
Start with cookies: true and rotateOn429: true — the most impactful settings. Add rotateAfterRequests only if the target applies per-session request quotas.