Postman Proxy Settings: Step-by-Step Setup

You usually open Postman to try an API, and the request goes out straight from your computer. In some cases, though, the request needs to come from another IP address: the API responds differently to requests from a particular country, the company network only lets you reach the internet through a proxy, or you are testing an integration's IP restriction. Postman offers two ways to handle this: use the operating system's proxy setting, or define a proxy specifically for Postman.

In this article we explain where Postman keeps its proxy settings, how to define a custom proxy step by step, how to add a username and password, and how to verify that the proxy is really working. Then we cover the bypass list, the most common connection errors and using a proxy with Newman on the command line.

How does Postman use a proxy?#

Postman sends the API requests you make from inside the desktop app. Whether those requests go through a proxy is decided by the settings on the Settings > Proxy tab. According to Postman's proxy documentation, there are two options for sending requests through a proxy:

• System proxy (Use the system proxy): Postman uses the operating system's proxy setting and the HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables. Practical if every application on the computer already goes through the same proxy.
• Custom proxy (Use custom proxy configuration): you define a proxy for Postman independently of the operating system. The right option if you only want API tests to go through the proxy and leave the browser and other applications untouched.

According to the documentation, if both options are on, Postman uses the custom proxy. To avoid confusion, we recommend keeping the option you do not use turned off.

Postman's interface can change between versions. The menu and field names in this article follow Postman's current documentation; you may see small differences in another version.

How do you define a custom proxy?#

1. Open the Postman desktop app, click the gear icon at the top right and go to Settings.
2. Switch to the Proxy tab in the window that opens.
3. In the section for sending requests, turn on Use custom proxy configuration.
4. In Use proxy for, choose which traffic the proxy is used for. Almost all APIs are HTTPS, so make sure HTTPS is selected; ticking both boxes is the safest choice.
5. In Proxy server, choose the protocol first. HTTP is usually enough for web APIs. If you use a SOCKS5 proxy, prefer SOCKS5H so that domain name resolution happens on the proxy side.
6. On the same line, enter the proxy server's address and port, for example pr.proxynet.io and 8000.
7. If the proxy requires a username and password, follow the steps in the next section.
8. Settings are saved automatically. Close the window and send a request to test.

Postman's documentation notes that only HTTP and HTTPS requests can be sent through a SOCKS proxy. You need to test proxy behaviour separately for other request types such as WebSocket or gRPC.

How do you add authentication?#

There are two ways to connect to a proxy: with a username and password, or by adding your computer's IP address to an allow list in the panel. We compare the two methods and their security in Proxy Authentication: User:Pass vs IP Whitelist.

With a username and password:

1. On the Proxy tab, turn on Proxy auth.
2. Enter the credentials from your panel in the Username and Password fields.
3. Type the password into these fields as it is, without encoding. Encodings such as %40, which are needed for passwords written inside an address, are not needed here; Postman takes the credentials from separate fields and builds the Proxy-Authorization header itself.

With an IP whitelist:

1. With the proxy off, find your computer's public IP address. Sending a GET request to https://api.ipify.org in Postman is enough.
2. Add that address to the allowed IP list in your customer panel.
3. Leave Proxy auth off in Postman.

If your home connection's IP address changes, the whitelist stops working after a while; switching to a username and password is less hassle in that case.

How do you verify that the proxy works?#

After saving the settings, send a request to an address that returns your IP address to see that the request really goes through the proxy.

1. Open a new request tab and leave the method as GET.
2. Type https://httpbin.org/ip in the address bar and click Send.
3. Look at the origin value in the response body.

{
  "origin": "203.0.113.25"
}

This should be the proxy's exit IP address. If you see your own IP address, the request is not going through the proxy; check that the custom proxy switch is on and that HTTPS is selected under Use proxy for.

To see the details of a request, open the Postman Console (the Console button in the bottom bar). The console shows the headers sent, the response time and the full text of any connection error. It is the first place to look when debugging.

You can run the same check from the command line. If a request does not work in Postman, trying the same proxy with cURL quickly shows whether the problem is in Postman's settings or in the proxy:

curl -x "http://user:pass@pr.proxynet.io:8000" https://httpbin.org/ip

If cURL works and Postman doesn't, the problem is in Postman's settings. If cURL fails too, check the proxy credentials or your network. cURL's proxy options are covered in How to Use a Proxy with cURL.

What is the bypass list for?#

The Proxy bypass field takes a comma-separated list of addresses that should not go through the proxy. You need it most in these situations:

• Local development server. When you test your API running on localhost:3000, sending the request to the proxy makes no sense; the proxy cannot reach an address on your local network anyway.
• Internal services. Internal services in the 10.0.0.0 block or with .local names.
• Authentication servers. If the service you get a token from has no IP restriction and only the main API request needs to go through the proxy.

Example value:

localhost,127.0.0.1,*.company.local,10.0.0.5

Local addresses you forget to add to the bypass list time out while the proxy is on, or end in an error page returned by the proxy.

Testing location-based API responses#

One of the most common reasons to use a proxy in Postman is to see how an API responds to requests from different countries. A pricing service may change the currency, a content API the language and catalogue, and a payment service the supported methods based on the country the request comes from.

A workable routine for these tests:

1. Prepare separate proxy details for each country.
2. In Postman, create an Environment for each country and store the expected currency, language and similar values as variables.
3. Change the proxy setting to the exit point of the country being tested.
4. Write a check in the request's Tests tab that compares the expected value.

pm.test("Currency matches the country", () => {
  const body = pm.response.json();
  pm.expect(body.currency).to.eql(pm.environment.get("expectedCurrency"));
});

Postman's proxy setting applies to the whole app, not per environment. When switching countries you also have to change the proxy address on the Settings screen. If you test many countries regularly, automating it with Newman as shown below is more practical. The localisation testing setup is on our localization solution page, and general application testing scenarios on our app testing solution page.

If every test needs a different exit IP, a Rotating Proxy, which gives a new IP on every connection without changing the address, can be used. If the IP needs to stay the same throughout the test, choose a fixed address.

Common errors and fixes#

A note on SSL verification. A fix often suggested online is to turn off SSL certificate verification on the Settings screen. A normal forward proxy carries HTTPS traffic through a CONNECT tunnel and does not touch certificates, so you should not get certificate errors with a standard proxy. If you do, something in between is decrypting the traffic. Adding that system's certificate instead of turning verification off keeps you from missing a real security problem.

The general meaning of HTTP status codes and retry logic is covered in HTTP Status Codes in Web Scraping.

Using a proxy on the command line with Newman#

Newman, used to run Postman collections in CI pipelines or scheduled jobs, does not read the desktop app's proxy settings. Newman's README says it uses the standard environment variables for proxies: HTTP_PROXY, HTTPS_PROXY and NO_PROXY.

On Linux and macOS:

export HTTPS_PROXY="http://user:pass@pr.proxynet.io:8000"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1"

newman run collection.json -e environment-de.json

In Windows PowerShell:

$env:HTTPS_PROXY = "http://user:pass@pr.proxynet.io:8000"
$env:HTTP_PROXY = $env:HTTPS_PROXY
$env:NO_PROXY = "localhost,127.0.0.1"

newman run collection.json -e environment-de.json

Because the address in the environment variable is a URL, characters such as @, : or / in the password must be encoded: @ is written as %40.

A script that tests different countries in turn can run the same collection while changing the environment variable and the Postman environment file each time:

#!/usr/bin/env bash
set -euo pipefail

for country in de fr tr; do
  export HTTPS_PROXY="http://user-${country}:pass@pr.proxynet.io:8000"
  newman run collection.json -e "environment-${country}.json" --reporters cli,junit \
    --reporter-junit-export "result-${country}.xml"
done

The user-${country} format here is only an example; whether the country is selected through the username, a different port or the panel depends on the provider. You can find the right format in your customer panel. If you use Postman's newer command-line tool, the Postman CLI, check its own documentation for proxy settings.

Use cases#

• A team testing location-based API behaviour: runs the same collection with exit points in different countries. An HTTPS Proxy is enough for web APIs.
• A developer verifying an IP-restricted integration: if the other side only allows requests from a specific fixed IP, they route Postman through a proxy with that IP and test the integration before going live.
• A user on a corporate network: if the company only allows internet access through a proxy, the system proxy option is enough; with TLS inspection, the company certificate is added.
• A QA team examining rate limit behaviour: checks how an API responds to consecutive requests from the same IP and whether it returns the Retry-After header correctly.

Decision guide#

Frequently asked questions#

Does the Postman web app have proxy settings?#

According to Postman's documentation, Postman's own default proxy cannot be configured in the web app; the system proxy or custom proxy options are used for sending requests. The desktop app is more practical for seeing and controlling all settings on one screen.

Can a proxy be set for a single collection only?#

In the desktop app the proxy setting applies to the whole app; it is not set per collection or environment. If different collections need different proxies, giving Newman a different environment variable on each run is the cleanest way.

Does a proxy affect Postman's own sync while it's on?#

Postman keeps separate settings for its own traffic, which syncs with your account, and for the API requests you send. The setting described in this article is for the requests you send.

My password has special characters. Should I put it in the address?#

In the Postman desktop app, type the password into the Password field without encoding it. In Newman, the password goes inside the URL in the environment variable, so @, : and / must be encoded.

Why did my requests get slower with a proxy?#

Every request has an extra hop, and the difference becomes noticeable when the proxy's exit point is far from the API you are testing. Postman's response time indicator and the console show whether the time is spent on the connection or on the server's response.

Should I choose SOCKS5 or HTTP?#

If you only send HTTP and HTTPS API requests from Postman, an HTTP proxy is enough and causes the fewest problems. If you only have a SOCKS5 proxy, use the SOCKS5H option. The difference between the two protocols is in SOCKS vs HTTP Proxy.

Summary#

In Postman, a proxy is set on the Settings > Proxy tab, either by using the operating system's setting or with a Postman-specific configuration. For a custom proxy, enter the server, port and protocol; if authentication is required, type the password unencoded into its own field. Verify the setup with a request to https://httpbin.org/ip, add local addresses to the bypass list, and use the HTTPS_PROXY environment variable for Newman in CI pipelines. For how proxies work in general, see What Is a Proxy Server and How Does It Work?; for plans that suit your API tests, take a look at our proxy services.