INTLanguages & Libraries

How to Use KnoxProxy with Swift URLSession

Route HTTP requests through KnoxProxy using Apple's built-in URLSession. Works on iOS, macOS, tvOS, and watchOS with no external dependencies.

5 minutes setupVerified against Swift URLSession · Jul 2026 · Swift 5.9 / iOS 17Language: Swift

01Steps

Configure Swift URLSession

Configure proxy dictionary

Set up URLSessionConfiguration with KnoxProxy connection details.

bash

let config = URLSessionConfiguration.default
config.connectionProxyDictionary = [
    kCFNetworkProxiesHTTPEnable: true,
    kCFNetworkProxiesHTTPProxy: "gw.knoxproxy.com",
    kCFNetworkProxiesHTTPPort: 7000,
    kCFStreamPropertyHTTPSProxyHost: "gw.knoxproxy.com",
    kCFStreamPropertyHTTPSProxyPort: 7000,
]

Create a URLSession

Initialize a session with the proxy configuration.

bash

let session = URLSession(configuration: config)

Make a proxied request

Send a GET request through KnoxProxy.

bash

let url = URL(string: "https://httpbin.org/ip")!
let task = session.dataTask(with: url) { data, response, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    }
}
task.resume()

Add proxy authentication

Handle 407 challenges with a URLSessionDelegate.

bash

class ProxyDelegate: NSObject, URLSessionDelegate {
    func urlSession(
        _ session: URLSession,
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
    ) {
        if challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodHTTPBasic {
            let credential = URLCredential(
                user: "USER",
                password: "PASS",
                persistence: .forSession
            )
            completionHandler(.useCredential, credential)
        } else {
            completionHandler(.performDefaultHandling, nil)
        }
    }
}

let session = URLSession(
    configuration: config,
    delegate: ProxyDelegate(),
    delegateQueue: nil
)

Country targeting

Target a specific country by changing the proxy username.

bash

// In the delegate, change the username:
let credential = URLCredential(
    user: "USER-country-gb",
    password: "PASS",
    persistence: .forSession
)

Async/await usage

Use modern Swift concurrency with the proxied session.

bash

let (data, response) = try await session.data(from: url)
let httpResponse = response as! HTTPURLResponse
print("Status: \(httpResponse.statusCode)")
print(String(data: data, encoding: .utf8) ?? "")

02Values

Copy-paste config

KnoxProxyURLSession.swift

import Foundation

class ProxyDelegate: NSObject, URLSessionDelegate {
    func urlSession(
        _ session: URLSession,
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
    ) {
        let credential = URLCredential(
            user: "USER", password: "PASS", persistence: .forSession
        )
        completionHandler(.useCredential, credential)
    }
}

let config = URLSessionConfiguration.default
config.connectionProxyDictionary = [
    kCFNetworkProxiesHTTPEnable: true,
    kCFNetworkProxiesHTTPProxy: "gw.knoxproxy.com",
    kCFNetworkProxiesHTTPPort: 7000,
    kCFStreamPropertyHTTPSProxyHost: "gw.knoxproxy.com",
    kCFStreamPropertyHTTPSProxyPort: 7000,
]

let session = URLSession(
    configuration: config, delegate: ProxyDelegate(), delegateQueue: nil
)

let url = URL(string: "https://httpbin.org/ip")!
let task = session.dataTask(with: url) { data, _, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    } else if let error = error {
        print("Error: \(error.localizedDescription)")
    }
}
task.resume()

RunLoop.main.run(until: Date(timeIntervalSinceNow: 10))

Rotation config

Each URLSession task gets a fresh exit IP. For sticky sessions, set the username to USER-session-{id} in the delegate credential.

Swift URLSession integration troubleshooting guide
Problem	Fix
NSURLErrorDomain Code=-1012 (authentication required)	Implement urlSession(_:didReceive:completionHandler:) in your URLSessionDelegate and return the proxy credential.
NSURLErrorDomain Code=-1004 (could not connect)	Verify gw.knoxproxy.com:7000 is reachable. Check that connectionProxyDictionary uses the correct key constants.

Before you start

Prerequisites

Xcode 15+ / Swift 5.9+

Apple platform target (iOS, macOS, etc.)

KnoxProxy account

Authentication

Auth method comparison

URLSessionDelegate (407 challenge)RecommendedNative Apple API; credentials never in URL. Requires delegate boilerplate

IP AllowlistNo delegate code needed. Static IP required; not feasible on mobile networks

All routing lives in the username

Anatomy of the credential string

USER-country-de-city-berlin-session-profile07

country-de -- geo, firstcity-berlin -- optional city pinsession-profile07 -- unique per Swift URLSession profile

Order 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.

Failure modes & fixes

NSURLErrorDomain Code=-1012 (authentication required) -- Proxy returned 407 but no delegate handles the challenge.
NSURLErrorDomain Code=-1004 (could not connect) -- Wrong proxy host or port, or network blocking the connection.

Verify before you trust it

IP checker confirms country and ASN match your target
Response status is 200, not 403 or 407
No repeated timeouts on the first few requests
Rotation or stickiness behaves as configured

FAQ

Swift URLSession + KnoxProxy, answered

Does URLSession support SOCKS5 proxies?

Yes, on macOS. Set kCFStreamPropertySOCKSProxyHost and kCFStreamPropertySOCKSProxyPort in connectionProxyDictionary with port 7001.

Can I use this with SwiftUI and async/await?

Yes. Create the proxied URLSession once and call try await session.data(from: url) in any async context.

How do I rotate IPs between requests?

Each new dataTask gets a fresh IP by default. Avoid connection reuse by creating a new URLSessionConfiguration per request if needed.

Will this work on iOS with cellular data?

Yes. URLSession respects connectionProxyDictionary on both Wi-Fi and cellular. IP allowlisting is not practical on mobile; use username/password auth.

RELMore integrations

Start using Swift URLSession with KnoxProxy

Free trial on rotating residential -- 5 minutes setup, no credit card.

Start for free See pricing

Configure Swift URLSession

Configure proxy dictionary

Set up URLSessionConfiguration with KnoxProxy connection details.

bash

let config = URLSessionConfiguration.default
config.connectionProxyDictionary = [
    kCFNetworkProxiesHTTPEnable: true,
    kCFNetworkProxiesHTTPProxy: "gw.knoxproxy.com",
    kCFNetworkProxiesHTTPPort: 7000,
    kCFStreamPropertyHTTPSProxyHost: "gw.knoxproxy.com",
    kCFStreamPropertyHTTPSProxyPort: 7000,
]

Create a URLSession

Initialize a session with the proxy configuration.

bash

let session = URLSession(configuration: config)

Make a proxied request

Send a GET request through KnoxProxy.

bash

let url = URL(string: "https://httpbin.org/ip")!
let task = session.dataTask(with: url) { data, response, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    }
}
task.resume()

Add proxy authentication

Handle 407 challenges with a URLSessionDelegate.

bash

class ProxyDelegate: NSObject, URLSessionDelegate {
    func urlSession(
        _ session: URLSession,
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
    ) {
        if challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodHTTPBasic {
            let credential = URLCredential(
                user: "USER",
                password: "PASS",
                persistence: .forSession
            )
            completionHandler(.useCredential, credential)
        } else {
            completionHandler(.performDefaultHandling, nil)
        }
    }
}

let session = URLSession(
    configuration: config,
    delegate: ProxyDelegate(),
    delegateQueue: nil
)

Country targeting

Target a specific country by changing the proxy username.

bash

// In the delegate, change the username:
let credential = URLCredential(
    user: "USER-country-gb",
    password: "PASS",
    persistence: .forSession
)

Async/await usage

Use modern Swift concurrency with the proxied session.

bash

let (data, response) = try await session.data(from: url)
let httpResponse = response as! HTTPURLResponse
print("Status: \(httpResponse.statusCode)")
print(String(data: data, encoding: .utf8) ?? "")

Copy-paste config

KnoxProxyURLSession.swift

import Foundation

class ProxyDelegate: NSObject, URLSessionDelegate {
    func urlSession(
        _ session: URLSession,
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
    ) {
        let credential = URLCredential(
            user: "USER", password: "PASS", persistence: .forSession
        )
        completionHandler(.useCredential, credential)
    }
}

let config = URLSessionConfiguration.default
config.connectionProxyDictionary = [
    kCFNetworkProxiesHTTPEnable: true,
    kCFNetworkProxiesHTTPProxy: "gw.knoxproxy.com",
    kCFNetworkProxiesHTTPPort: 7000,
    kCFStreamPropertyHTTPSProxyHost: "gw.knoxproxy.com",
    kCFStreamPropertyHTTPSProxyPort: 7000,
]

let session = URLSession(
    configuration: config, delegate: ProxyDelegate(), delegateQueue: nil
)

let url = URL(string: "https://httpbin.org/ip")!
let task = session.dataTask(with: url) { data, _, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    } else if let error = error {
        print("Error: \(error.localizedDescription)")
    }
}
task.resume()

RunLoop.main.run(until: Date(timeIntervalSinceNow: 10))

Rotation config

Each URLSession task gets a fresh exit IP. For sticky sessions, set the username to USER-session-{id} in the delegate credential.

Swift URLSession integration troubleshooting guide
Problem	Fix
NSURLErrorDomain Code=-1012 (authentication required)	Implement urlSession(_:didReceive:completionHandler:) in your URLSessionDelegate and return the proxy credential.
NSURLErrorDomain Code=-1004 (could not connect)	Verify gw.knoxproxy.com:7000 is reachable. Check that connectionProxyDictionary uses the correct key constants.

How to Use KnoxProxy with Swift URLSession

Configure Swift URLSession

Copy-paste config

Prerequisites

Auth method comparison

Anatomy of the credential string

Failure modes & fixes

Verify before you trust it

Swift URLSession + KnoxProxy, answered

Related tools

Start using Swift URLSession with KnoxProxy

How to Use KnoxProxy with Swift URLSession

Configure Swift URLSession

Copy-paste config

Prerequisites

Auth method comparison

Anatomy of the credential string

Failure modes & fixes

Verify before you trust it

Swift URLSession + KnoxProxy, answered

Related tools

Start using Swift URLSession with KnoxProxy