How to Add Proxy in Postman: The Complete Guide

As API development becomes increasingly complex, the need to debug traffic from behind corporate firewalls or simulate requests from different global locations is critical. Postman, the industry-standard API testing tool, offers robust proxy capabilities that allow developers to route traffic through an intermediary server.

This guide covers everything you need to know about configuring proxies in Postman, from basic setup to advanced interception for security testing.

Understanding Proxies in API Development

Before diving into configuration, it is essential to understand *why* proxies are used in the context of API testing:

1. Traffic Interception: Debugging API calls by inspecting the raw HTTP/S traffic to see headers, payloads, and cookies that are sometimes abstracted by the UI. 2. Geolocation Testing: Routing requests through a proxy server in a different country to test localization or geo-restricted content. 3. Network Simulation: Simulating high-latency networks or testing how an API behaves when requests come from a specific IP whitelist. 4. Corporate Firewalls: Accessing external APIs that are blocked by strict network policies.

Method 1: Configuring the Global Application Proxy

The most common method is configuring Postman to route *all* traffic through a specific server. This is useful if you are working in a restricted environment or using a tool like Fiddler or Charles to capture traffic.

Step-by-Step Instructions:

1. Open Settings: Click the gear icon (Settings) located in the top-right header of the Postman application. 2. Navigate to Proxy: In the Settings modal, select the Proxy tab from the left sidebar. 3. Enable Global Proxy: Check the box labeled "Use a global proxy. 4. Enter Server Details: * Proxy Host: Enter the IP address (e.g., 127.0.0.1) or domain name of your proxy server. * Port: Enter the port number (e.g., 8080). 5. Save: Click the Save/Check icon to apply changes.

Proxy Authentication

If your proxy server requires a username and password (common in corporate environments):

1. In the same Proxy tab, locate the "Proxy Authentication" section. 2. Enter your Username and Password. 3. These credentials are stored securely in Postman's local keychain.

> Note: Once enabled, every request you send from Postman will attempt to route through this server. If the proxy is offline, your requests will fail.

Method 2: Using the System Proxy

Postman is designed to respect your operating system's proxy settings automatically. This is often the easiest method for users in corporate environments.

How it Works:

If you have configured a proxy at the OS level (Windows Internet Options, macOS Network Settings, or Linux environment variables), Postman detects it automatically upon launch.

• Windows: Settings > Network & Internet > Proxy.
• macOS: System Settings > Network > Wi-Fi/Ethernet > Details > Proxies.

Postman generally defaults to the System Proxy unless you explicitly override it in the "Global Proxy" settings mentioned in Method 1.

Method 3: Routing Specific Requests (Manual Configuration)

While Postman's UI primarily handles global or system-wide settings, you might need to route a *single* request through a specific proxy without affecting others.

Using Pre-Request Scripts

You can program specific requests to use a proxy by using the pm.sendRequest method combined with a proxy agent, although this is more advanced and typically used in the Postman CLI or Newman.

However, a simpler workflow within the UI is to toggle the Global Proxy on only when sending that specific request, or use a dedicated browser extension alongside the Postman web app.

Method 4: Debugging with Burp Suite (Interceptor)

A very common use case for "adding a proxy" in Postman is to intercept traffic for security analysis using Burp Suite.

Workflow:

1. Open Burp Suite: Navigate to Proxy > Options. 2. Set Listener: Ensure your Burp listener is running on 127.0.0.1:8080. 3. Configure Postman: Follow Method 1 above. Set the Postman Global Proxy Host to 127.0.0.1 and Port to 8080. 4. Disable HTTPS Checking (Optional): If you run into SSL errors, you may need to configure Burp's CA certificate in your system trust store, though Postman often handles self-signed certs with a warning confirmation.

Now, every request sent from Postman will appear in the Burp Suite "Proxy > Intercept" tab, allowing you to modify parameters before forwarding them to the target server.

Troubleshooting Common Proxy Issues

Connection Refused / ECONNREFUSED

• Cause: Postman cannot reach the proxy server.
• Fix: Verify the Host and Port. Ensure the proxy software (e.g., Burp, Squid, CCProxy) is actually running. If using a local tool, check if it is binding to 127.0.0.1 or localhost.

Proxy Authentication Failed

• Cause: Incorrect credentials or NTLM authentication issues.
• Fix: Double-check the username/password in Postman's Proxy Authentication settings. Note that Postman supports Basic auth well but may struggle with Kerberos/NTLM without additional system configuration.

SSL Certificate Errors

• Cause: The proxy is performing a "Man-in-the-Middle" attack on HTTPS traffic by generating its own certificate.
• Fix: You must turn off SSL Certificate Verification in Postman.

* Go to Settings > Settings. * Toggle "SSL certificate verification" to OFF. * *Warning:* Only do this in a secure development environment to prevent potential security risks.

Comparison: Global vs. System Proxy

| Feature | Global Proxy (App Setting) | System Proxy (OS Setting) | | :--- | :--- | :--- | | Configuration Location | Postman Settings > Proxy Tab | OS Network Settings | | Scope | Affects only Postman requests | Affects all apps (Chrome, Edge, etc.) | | Auth Support | Built-in UI for User/Pass | Handled by OS Dialogs | | Priority | Higher (Overrides System if set) | Default (Used if Global is off) | | Best For | Interception (Burp/Fiddler), specific tasks | Corporate VPNs, persistent network config |

Advanced: Automating with Postman CLI (Newman)

If you are running your collections in a CI/CD pipeline using Newman (the command-line runner for Postman), you can pass the proxy configuration via the command line argument rather than hardcoding it in the app.

Command:

newman run MyCollection.postman_collection.json --proxy "http://192.168.1.5:8080"

If authentication is required, you can utilize environment variables for the username and password within your collection scripts.

Conclusion

Adding a proxy in Postman is a fundamental skill for advanced API testing. Whether you are troubleshooting firewall issues, capturing packets for security auditing, or spoofing locations, the flexibility of Postman's proxy settings allows for a seamless workflow.

For general browsing, rely on the System Proxy. For targeted security testing and interception, configure the Global Proxy settings to route traffic through your preferred interception tool. Always remember to disable the proxy when finished to restore standard direct connection speeds.