NEW LOWER PRICES!All plans now up to 15% cheaper — Same trusted quality, same stability — just better pricing!
View Plans
Telegram

Java (HttpClient, OkHttp)

Configure a proxy in Java with the built-in HttpClient and OkHttp. Add authentication and route HTTP/SOCKS5 traffic with examples.

Integrations5 min read

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.

Note

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.

Java
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": ..., ...}
    }
}
Warning

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.

Tip

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(...).

Java
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());
        }
    }
}
Note

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):

Java
// 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:

Java
// 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.

Warning

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:

Java
// IP-authenticated — no Authenticator needed
HttpClient client = HttpClient.newBuilder()
    .proxy(ProxySelector.of(
        new InetSocketAddress("gw-2312.coldproxy.com", 30000)))
    .build();
Note

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 407 over HTTPS with the JDK client almost always means the disabledSchemes properties 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

Tailored Commercial Plans

Have a Large Project?

When the public plans don’t quite fit, ColdProxy can shape a tailored commercial plan around your workflow — custom speed tiers, custom monthly GB limits, and a plan built from Residential IPv4, Residential IPv6, or Datacenter IPv6.

  • Custom speed & GB quotasCustom speed and monthly GB limits set to match how much traffic you run and which proxy types you use.
  • Across the product lineupResidential IPv4 (Unmetered or GB-based), Residential IPv6, and Datacenter IPv6, sized to fit your project.
  • Built around your workflowPricing, capacity, and session settings (rotating or sticky) matched to your project instead of a fixed package.
Contact Our Sales TeamTelegram & ticket support · English and Arabic