Java gives you two solid ways to set up a proxy: the built-in JDK HttpClient (Java 11+) and OkHttp. This page routes Java HTTP traffic through ColdProxy's gateway gw-{service-id}.coldproxy.com on any port in 30000-34999 with both. Each client supports USERNAME:PASSWORD auth (and OkHttp adds a SOCKS option), and both let you switch between rotating and sticky exits purely through ColdProxy's username tags. The examples use gw-2312.coldproxy.com (replace 2312 with your service/package ID) and the credentials from your client area. For background on the auth models, see IP whitelisting vs username/password.
After order delivery, allow about 10-20 minutes for the proxies to authenticate and activate.
Connection details
| Setting | Value |
|---|---|
| Host | gw-{service-id}.coldproxy.com — examples use gw-2312 |
| Port | Any in 30000-34999 (use 30000 in examples) |
| Protocols | HTTP, HTTPS (TCP) and SOCKS5 (TCP/UDP), auto-detected |
| Auth | USERNAME:PASSWORD, or IP whitelisting (up to 50 IPs) |
| String format | gw-2312.coldproxy.com:PORT:USERNAME:PASSWORD |
JDK HttpClient proxy (Java 11+)
The built-in java.net.http.HttpClient takes a ProxySelector via .proxy(...) and proxy credentials via .authenticator(...). Supply a PasswordAuthentication from your Authenticator, guarded by getRequestorType() == RequestorType.PROXY so your credentials are only sent to the proxy, never to the destination site.
import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class ColdProxyExample {
public static void main(String[] args) throws Exception {
// Required for Basic proxy auth over HTTPS tunnels (see WARNING below)
System.setProperty("jdk.http.auth.tunneling.disabledSchemes", "");
System.setProperty("jdk.http.auth.proxying.disabledSchemes", "");
String user = "USERNAME";
String pass = "PASSWORD";
HttpClient client = HttpClient.newBuilder()
.proxy(ProxySelector.of(
new InetSocketAddress("gw-2312.coldproxy.com", 30000)))
.authenticator(new Authenticator() {
@Override
protected PasswordAuthentication getPasswordAuthentication() {
if (getRequestorType() == RequestorType.PROXY) {
return new PasswordAuthentication(user, pass.toCharArray());
}
return null;
}
})
.build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.vipv6proxy.com/api/checker/my-ip"))
.build();
HttpResponse<String> response =
client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body()); // JSON: {"ip": "...", "version": ..., ...}
}
}To address CVE-2016-5597, modern JDKs disable Basic authentication for proxies during HTTPS tunneling (the CONNECT step). Without the two disabledSchemes system properties set to an empty string, HTTPS requests through an authenticated proxy fail with 407 Proxy Authentication Required. Set them before the first request (ideally as JVM flags -Djdk.http.auth.tunneling.disabledSchemes="" -Djdk.http.auth.proxying.disabledSchemes="") and only for trusted proxy endpoints like ColdProxy.
Verify the exit IP and location with the Proxy Checker and What Is My IP tools before scaling up.
OkHttp proxy
OkHttp configures the proxy with a java.net.Proxy and handles 407 challenges with a proxyAuthenticator that attaches a Proxy-Authorization header built by Credentials.basic(...).
import java.net.InetSocketAddress;
import java.net.Proxy;
import okhttp3.Credentials;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
public class ColdProxyOkHttp {
public static void main(String[] args) throws Exception {
String user = "USERNAME";
String pass = "PASSWORD";
Proxy proxy = new Proxy(Proxy.Type.HTTP,
new InetSocketAddress("gw-2312.coldproxy.com", 30000));
OkHttpClient client = new OkHttpClient.Builder()
.proxy(proxy)
.proxyAuthenticator((route, response) -> {
if (response.request().header("Proxy-Authorization") != null) {
return null; // already failed with these credentials: give up
}
String credential = Credentials.basic(user, pass);
return response.request().newBuilder()
.header("Proxy-Authorization", credential)
.build();
})
.build();
Request request = new Request.Builder()
.url("https://api.vipv6proxy.com/api/checker/my-ip")
.build();
try (Response response = client.newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}OkHttp also supports SOCKS via new Proxy(Proxy.Type.SOCKS, new InetSocketAddress(host, port)). ColdProxy supports SOCKS5 over TCP and UDP, but OkHttp performs proxy authentication through the proxyAuthenticator (an HTTP-style challenge), so the HTTP proxy type with the example above is the most reliable path for credentialed requests. See SOCKS5 vs HTTPS proxies and TCP vs UDP proxies.
Rotating vs sticky sessions
ColdProxy encodes geo-targeting and session behavior in the username, using a user-key-value-key-value... grammar (full reference: Username tag scheme). You switch between a fresh IP per request and a held IP by changing the user string passed to your Authenticator (JDK HttpClient) or Credentials.basic(...) (OkHttp): no separate API call. Set connect and request timeouts on both clients (HttpClient.newBuilder().connectTimeout(...), HttpRequest...timeout(...), OkHttp's callTimeout) so a stalled connection fails fast.
Rotating (new IP per request)
With no session tag, each request gets a new IP. Add geo tags to target a country/state/city (here a rotating US exit):
// Rotating US exit IP — confirm the exact country prefix in your client area
String user = "user-country-us";
String pass = "PASSWORD";Sticky (hold the same IP)
A sticky session needs both a session tag and a time (duration) tag together; supplying only one rotates per request. This holds one US IP for 10 minutes:
// Sticky US IP for 10 minutes — same session ID + duration reuses the exit IP
String user = "user-country-us-session-481516-time-10m";
String pass = "PASSWORD";Drop these into the user variable in either example above; the rest of the client setup is unchanged.
The exact segment prefixes (for example the keys for country, session, and time) are configured per product by ColdProxy; confirm the exact prefixes for your plan in your client area before deploying. Sticky duration limits: Residential IPv4 supports 5s to 24h; Residential IPv6 and Datacenter IPv6 support 5s up to FOREVER.
For the concepts, see rotating and sticky proxies explained and geo-targeting with proxies.
IP whitelist alternative
Authorize your server's public IP (up to 50 addresses) in the client area and you can skip credentials entirely; omit the .authenticator(...) (JDK) or .proxyAuthenticator(...) (OkHttp) and just point the proxy at the gateway:
// IP-authenticated — no Authenticator needed
HttpClient client = HttpClient.newBuilder()
.proxy(ProxySelector.of(
new InetSocketAddress("gw-2312.coldproxy.com", 30000)))
.build();IP authentication and username/password can both be active at once. With IP-auth and no username tags, the geo defaults to Worldwide. To bind geo-targeting and sticky behavior to specific ports without per-request username tags, configure SuperPorts (port-range rules) in your client area (for example, ports 30000-31000 fixed to US with a 10-minute sticky window).
Verify and troubleshoot
- Confirm reachability, exit IP, and location with the Proxy Checker and What Is My IP tools.
- A persistent
407over HTTPS with the JDK client almost always means thedisabledSchemesproperties are not set (see the warning above). See proxy error codes 407, 403, 429, 502, 504. - On an IPv6 plan, check the target with the IPv6 Checker first; IPv4-only sites (no AAAA record) will fail over IPv6. Confirmed IPv6-ready platforms include Google, YouTube, Facebook, Instagram, WhatsApp, Bing, Yahoo, Netflix, and LinkedIn.
Next steps
- Compare plans and short paid validation options on pricing and the proxy product pages.
- See proxy automation and API integration for building rotation and provisioning into a Java service.