OkHttp is the most popular HTTP client for Kotlin and Android. Route requests through KnoxProxy with first-class proxy and authenticator support.
Add the OkHttp dependency to your build.gradle.kts.
// build.gradle.kts
dependencies {
implementation("com.squareup.okhttp3:okhttp:4.12.0")
}Configure the client with KnoxProxy as an HTTP proxy.
import okhttp3.*
import java.net.InetSocketAddress
import java.net.Proxy
val proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("gw.knoxproxy.com", 7000))
val client = OkHttpClient.Builder()
.proxy(proxy)
.proxyAuthenticator { _, response ->
response.request.newBuilder()
.header("Proxy-Authorization", Credentials.basic("USER", "PASS"))
.build()
}
.build()Send a GET request through the proxy.
val request = Request.Builder()
.url("https://httpbin.org/ip")
.build()
client.newCall(request).execute().use { response ->
println(response.body?.string())
}Target a specific country by adjusting the proxy username.
val proxyAuth = Credentials.basic("USER-country-us", "PASS")
val client = OkHttpClient.Builder()
.proxy(proxy)
.proxyAuthenticator { _, response ->
response.request.newBuilder()
.header("Proxy-Authorization", proxyAuth)
.build()
}
.build()Maintain the same IP across requests with a session ID.
val stickyAuth = Credentials.basic("USER-session-abc123", "PASS")
val stickyClient = OkHttpClient.Builder()
.proxy(proxy)
.proxyAuthenticator { _, response ->
response.request.newBuilder()
.header("Proxy-Authorization", stickyAuth)
.build()
}
.build()Use the SOCKS5 gateway for TCP-level proxying.
val socks5Proxy = Proxy(Proxy.Type.SOCKS, InetSocketAddress("gw.knoxproxy.com", 7001))
val socksClient = OkHttpClient.Builder()
.proxy(socks5Proxy)
.proxyAuthenticator { _, response ->
response.request.newBuilder()
.header("Proxy-Authorization", Credentials.basic("USER", "PASS"))
.build()
}
.build()import okhttp3.*
import java.net.InetSocketAddress
import java.net.Proxy
fun main() {
val proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("gw.knoxproxy.com", 7000))
val client = OkHttpClient.Builder()
.proxy(proxy)
.proxyAuthenticator { _, response ->
response.request.newBuilder()
.header("Proxy-Authorization", Credentials.basic("USER", "PASS"))
.build()
}
.build()
val request = Request.Builder()
.url("https://httpbin.org/ip")
.build()
client.newCall(request).execute().use { response ->
println("Status: ${response.code}")
println("Body: ${response.body?.string()}")
}
}Each request gets a fresh IP by default. For sticky sessions, append -session-{id} to the username (e.g., USER-session-abc123). The same session ID reuses the same exit IP.
| Problem | Fix |
|---|---|
| java.net.SocketException: Connection reset | Verify the username and password. Ensure the Authenticator returns a valid Proxy-Authorization header. |
| java.io.IOException: unexpected end of stream | Increase OkHttpClient timeouts with connectTimeout() and readTimeout(). Retry the request. |
| HTTP 407 Proxy Authentication Required (loop) | Check for null response.request.header("Proxy-Authorization") to avoid infinite retry loops. Return null after the first attempt. |
USER-country-de-city-berlin-session-profile07Order matters -- geo flags before the session flag. The session name is free text; use the profile ID so the mapping is self-documenting. Password stays as issued; no flags belong there. HTTP on :7000, SOCKS5 on :7001, same credentials.
Yes. Build the Proxy object with Proxy.Type.SOCKS instead of Proxy.Type.HTTP, pointing at InetSocketAddress("gw.knoxproxy.com", 7001), the dedicated SOCKS5 port, rather than port 7000 used for HTTP. Pass that proxy into OkHttpClient.Builder().proxy(proxy) exactly as shown in the HTTP setup, keeping the same proxyAuthenticator block for credentials.
Retrofit is built directly on top of OkHttp, so it inherits whatever client configuration you give it. Build the proxied OkHttpClient shown above, with the KnoxProxy Proxy and proxyAuthenticator set, then pass it into Retrofit.Builder().client(client).build() before defining your API interfaces, and every Retrofit call routes through KnoxProxy automatically.
Yes, and it is the default behavior. Each new request through the proxied OkHttpClient gets a fresh KnoxProxy exit IP automatically, with no extra code required. To keep rotation working, do not append a -session-{id} suffix to the username in your proxyAuthenticator, since that suffix is what pins a request to one sticky IP instead.
Append -country-{cc} to the username inside your proxyAuthenticator, for example USER-country-de for Germany or USER-country-gb for the UK, in the Credentials.basic(user, pass) call. KnoxProxy reads that suffix and routes the request through its IP pool for that specific country instead of a random exit location.
Rotating residential proxies -- 5 minutes setup, instant activation, 14-day money-back guarantee.