PowerShell proxy setup and authentication

Short answers

Get the proxy fields before opening PowerShell

Open the connection builder, choose HTTP, then select the pool, country and rotation for your permitted task. Keep the gateway host and HTTP port together. Copy the full generated username, including its connection settings, and use the separate proxy password. Your website sign-in password and API key are different credentials. Do not put any of them in a support screenshot or a saved command.

This recipe targets PowerShell 7.6. Check $PSVersionTable.PSVersion in the terminal that will run it. Windows PowerShell 5.1 is a different runtime; this example does not claim compatibility with its older web client. For a scheduled job, check the executable chosen by the scheduler as well. A terminal profile and a background worker can launch different versions.

Send one request with explicit proxy credentials

Save the following as proxy-check.ps1, start PowerShell with pwsh -NoProfile, then run ./proxy-check.ps1. Enter the full generated username and password only when prompted. The code uses a small HTTPS echo endpoint so the first check has a simple expected result. It makes no account change and does not buy traffic, although a real gateway request can consume your existing GB balance.

$ErrorActionPreference = 'Stop'
$proxy = [uri]'http://gw.portproof.org:7000'
$target = [uri]'https://api.portproof.org/v1/echo-ip'
$credential = Get-Credential -Message 'Enter the full proxy username and proxy password'
try {
    if ($null -eq $credential -or [string]::IsNullOrWhiteSpace($credential.UserName)) {
        throw 'Enter the generated proxy username.'
    }
    $response = Invoke-WebRequest -Uri $target -Method Get -Proxy $proxy -ProxyCredential $credential -ConnectionTimeoutSeconds 10 -OperationTimeoutSeconds 10 -MaximumRedirection 0 -MaximumRetryCount 0 -ErrorAction Stop
    if ($response.StatusCode -ne 200) { throw 'The echo endpoint did not return HTTP 200.' }
    $payload = $response.Content | ConvertFrom-Json -ErrorAction Stop
    $address = $null
    if ($payload.ip -isnot [string] -or -not [System.Net.IPAddress]::TryParse($payload.ip, [ref]$address)) {
        throw 'The echo body did not contain a valid IP address.'
    }
    'HTTP 200; exit IP: ' + $address.ToString()
} catch {
    # Do not print complete exceptions or response bodies into shared logs.
    if ($null -ne $_.Exception.Response) {
        Write-Host ('HTTP status: ' + [int]$_.Exception.Response.StatusCode)
    }
    Write-Host 'Check failed. Check proxy credentials, gateway status, TLS and echo response.'
    exit 1
} finally {
    $credential = $null
}

A successful result prints HTTP 200 and the IP address returned by the echo endpoint. That address is what this destination saw for this request. It is not a country verification, a promise about the next connection, or evidence that another website will accept your request. Keep the output local if you do not want to share your current exit address.

Keep gateway and website authentication separate

-ProxyCredential belongs to the gateway selected by -Proxy. The destination uses a different authentication mechanism: -Credential or an application-specific token, when its API requires one. Do not substitute the proxy credential into those destination fields and do not build a manual Authorization header from it. The example deliberately sends no website credential.

The prompt keeps the password out of the script and the command arguments. Do not replace it with a literal password to make the example unattended. An unattended worker needs its own approved runtime secret store and a narrowly scoped credential retrieval step. Setting the variable to null at the end drops this reference; it is not a guarantee that every copy of a secret has been erased from memory.

An HTTP gateway and an HTTPS destination describe two different connection segments. Destination TLS remains checked inside the CONNECT tunnel. This does not encrypt the initial HTTP proxy authentication exchange between your computer and the gateway. Use a network you trust, and never remove certificate validation to make a failing test appear successful.

A request setting is not a Windows-wide setting

The explicit proxy parameters apply to this request. They do not configure your browser, change Windows proxy settings or rewrite another program’s environment. That narrow scope is useful when comparing a failing client with a known-good check: change one variable, rerun one request, and record the result before changing anything else. Loopback destinations can receive special direct-routing treatment; use the public echo endpoint for this check.

If a larger script behaves differently, look for a different web session, credentials or destination, then check its runtime and inherited proxy environment. Keep the same generated username during the comparison. The client-routing guide covers environment-variable differences; the curl test gives a separate client for a controlled comparison.

Use the timeouts as limits, not a job deadline

The request disables redirects and status-code retries. A redirect therefore needs your attention instead of silently sending the test elsewhere. An HTTP authentication challenge can still involve a second CONNECT exchange; disabling retries is not a promise of one packet or one gateway exchange. Keep this distinction when reading a proxy log.

ConnectionTimeoutSeconds limits how long a request can remain pending, but DNS resolution can exceed a short configured value. OperationTimeoutSeconds limits a stall between stream reads, not the total download duration. These settings are not a strict deadline for the entire script. The web cmdlet buffers this small response; it is not a bounded streaming downloader for arbitrary large files. A production collector needs a separate job deadline and response-size policy.

Find the failing stage before repeating the request

407 from the gateway

Recheck the full generated username and proxy password. Confirm that the account has usable traffic. Changing the destination password will not repair gateway authentication; use the 407 guide.

CONNECT or gateway failure

Compare the HTTP host and port with the builder, then check gateway availability and selected settings. A rejected tunnel has not produced a normal website response. The CONNECT guide explains the next checks.

401 or 403 from the website

The target can require its own credentials or refuse a request. Check its documented access rules. Do not repeatedly rotate connections to disregard that decision.

TLS, timeout or invalid echo body

Check the machine clock, approved trust configuration, network route and destination. HTTP 200 alone is insufficient if the JSON lacks an IP address. Keep certificate checks enabled and do not paste complete exceptions containing sensitive request details into shared logs.

What this example was checked against

Checked with PowerShell 7.6.6 on macOS: an authenticated local CONNECT proxy forwarded the HTTPS echo request to Portproof’s public echo endpoint. Local HTTP fixtures checked response validation, redirects, 401 and credential separation; local gateway failures and an untrusted TLS certificate were rejected. Synthetic credentials replaced the prompt, so its interactive UI was not tested. No live proxy pool was used. These checks establish client behaviour, not Windows compatibility, speed or pool availability.

The PowerShell 7.6 web-request reference documents the proxy, credential, redirect and timeout parameters. After the echo check, replace the destination only with an endpoint you are authorised to access. Add its own response validation and limits before expanding into a repeated workflow.

Read next