How to Use an Authenticated Proxy in PowerShell

For a PowerShell HTTP request, specify the proxy with -Proxy and pass its login as a PSCredential through -ProxyCredential. Use Get-Credential to prompt for the password instead of embedding it in a command or script.

This approach applies to Invoke-RestMethod and Invoke-WebRequest. It does not automatically configure browsers, Git, Docker or executables started from the same terminal. Each program uses its own networking implementation. Begin with one small IP check before adding application tokens or a scheduled task.

Check which PowerShell you are running

$PSVersionTable.PSVersion
Get-Command Invoke-RestMethod, Invoke-WebRequest

Windows PowerShell 5.1 and PowerShell 7 can coexist on the same Windows machine. Check the session that actually runs your script. A job started with powershell.exe can behave differently from one started with pwsh.exe, even when the script path is identical.

Both versions provide explicit proxy and proxy-credential parameters. Beginning with PowerShell 7.0, the web cmdlets also support proxy configuration from environment variables, through .NET’s default proxy handling. Do not assume that behavior is identical in Windows PowerShell 5.1. Check the version-specific Invoke-RestMethod reference.

PowerShell 7.4 and later: TimeoutSec remains an alias for ConnectionTimeoutSeconds. The separate OperationTimeoutSeconds parameter limits stalls between reads in a response stream; it is not a deadline for the entire download. For jobs on these versions, set both limits deliberately and add a separate job deadline when required. Keep version-specific options out of a script that must also run on Windows PowerShell 5.1. See the Microsoft parameter reference, reviewed 13 October 2026.

Use full cmdlet names in examples. In Windows PowerShell 5.1, curl may resolve to an alias for Invoke-WebRequest; curl.exe is a separate executable with different arguments. The command resolver shows what your shell will run.

Make one request with a credential prompt

Replace the reserved hostname and port with your HTTP proxy endpoint. Keep its credentials separate:

$proxyUri = [uri]'http://proxy.example.com:3128'
$proxyCredential = Get-Credential -Message 'Enter your proxy login'

$requestOptions = @{
    Uri = 'https://api.ipify.org?format=json'
    Proxy = $proxyUri
    ProxyCredential = $proxyCredential
    TimeoutSec = 30
    MaximumRedirection = 0
    ErrorAction = 'Stop'
}

$result = Invoke-RestMethod @requestOptions
$result.ip

Get-Credential returns a credential object containing the entered username and a SecureString password. It avoids placing the password in script text or command history. Keep that object private; do not convert it to plaintext merely to construct a proxy URL.

The destination in this example uses HTTPS. The proxy URL still starts with http:// because its scheme identifies the connection to the proxy. A compatible HTTP proxy establishes an HTTPS CONNECT tunnel. Confirm the proxy’s actual protocol rather than copying the destination’s scheme.

Compare the returned IP with your expected proxy exit. If you only compare it with your laptop’s IP, remember that the script could be running on a server or under another network route. After the check, substitute one read-only API operation and add the destination’s authentication separately.

-Credential belongs to the destination request; -ProxyCredential belongs to the proxy. Mixing them can produce a proxy 407 or an API 401. See our proxy authentication guide for this distinction.

Run the downloadable IP-check script

Download powershell-proxy-ip-check.ps1. Review the file, then run it from its folder:

.\powershell-proxy-ip-check.ps1 -ProxyUri 'http://proxy.example.com:3128'

The script prompts for credentials, performs a request and validates that the JSON response contains an IP address. It returns the observed IP and the proxy host/port without printing the password. It rejects credentials embedded in the proxy URI and disables redirects for this diagnostic request.

If you already have a credential object for this session, pass it explicitly:

.\powershell-proxy-ip-check.ps1 -ProxyUri $proxyUri -ProxyCredential $proxyCredential

This configuration template targets Windows PowerShell 5.1 and PowerShell 7. Verify its result with your endpoint before reusing it in a larger job. Credential routing, response validation and destination access are separate checks; an IP-check success only confirms the route used for that request.

If Windows blocks the downloaded script, inspect Get-ExecutionPolicy -List and follow the signing or trusted-file procedure permitted by your environment. Microsoft’s execution policy reference explains the applicable scopes.

Download a file or reuse proxy settings

Use Invoke-RestMethod when you want parsed JSON. For file downloads or a response object, use Invoke-WebRequest with the same explicit proxy settings:

$downloadOptions = @{
    Uri = 'https://example.com/'
    Proxy = $proxyUri
    ProxyCredential = $proxyCredential
    OutFile = '.\example-response.html'
    UseBasicParsing = $true
    TimeoutSec = 30
    ErrorAction = 'Stop'
}
Invoke-WebRequest @downloadOptions

-UseBasicParsing avoids the legacy page-parsing dependency in Windows PowerShell 5.1; newer PowerShell versions already use basic parsing. Microsoft’s 5.1 documentation describes that behavior. Choose a writable output path and inspect the saved content before treating a download as the expected file.

For several requests, reuse a small splatting hashtable with Proxy and ProxyCredential. Keep API tokens in destination-specific settings. Reuse is useful for consistency, but test each new hostname because successful proxy authentication does not promise destination access.

Understand environment settings and unattended jobs

PowerShell 7’s default proxy handling can read HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and NO_PROXY. The first two select destination protocols, the third provides a fallback, and the last specifies bypasses. The underlying .NET reference explains platform-dependent defaults.

For an authentication check, explicit parameters are easier to inspect than inherited environment settings. Start a fresh session after changing default proxy variables, then verify the actual route. Do not assume a child application follows PowerShell’s web-cmdlet configuration. See the Docker guide for its separate application and daemon settings.

For a Windows-integrated corporate proxy, -ProxyUseDefaultCredentials uses the executing identity’s credentials. It cannot be combined with -ProxyCredential and is not a substitute for a provider-issued username/password login.

An unattended job cannot answer an interactive credential prompt. Retrieve an approved credential from your existing secret-management system and pass a PSCredential object. Test under the scheduled task’s actual account. Avoid hard-coded passwords and authenticated URLs in arguments, environment dumps or logs.

Troubleshoot the error you received

Capture a sanitized error and your PowerShell version. Change one setting at a time. Check the endpoint with the proxy tester, and consult proxy errors before adding retries. Increasing a timeout cannot repair an incorrect password.

Frequently asked questions

Does this change Windows proxy settings?

No. The explicit parameters configure that web request. They do not rewrite the operating system’s proxy configuration.

Should I percent-encode the password entered in Get-Credential?

No. Enter the original password. URL encoding applies when credentials are represented inside a URL, which this example avoids.

Can I reuse the proxy credential for my API?

Use the API’s own credentials. The two services authenticate different connections and usually issue different logins.

Can I run the sample without internet access?

You can parse it locally. Its default IP-check request requires network access and a working proxy; a local fixture only tests controlled behavior.

For scripts needing a repeatable HTTP endpoint, compare BuyProxies dedicated proxy plans with your authentication and destination requirements. Find related setups in developer proxy examples.

Sources

• Invoke-RestMethod in PowerShell 7
• Invoke-RestMethod in Windows PowerShell 5.1
• Invoke-WebRequest in Windows PowerShell 5.1
• Get-Credential
• .NET default proxy handling
• PowerShell execution policies

Technical references reviewed October 2, 2026. See our editorial policy and testing methodology.

Compare the verified client versions, protocols and test conditions before choosing a configuration. The matrix separates tested cases from untested environments.