Postman Proxy Setup: Authenticated API Testing
Configure Postman's proxy settings, keep proxy and API credentials separate, verify the exit address, and script repeatable response checks.
Instead of changing network settings and retrying failed requests by hand, complete your Postman proxy setup in the desktop app, authenticate to the proxy separately from the API, and verify the exit address before testing application behavior. This workflow takes you from a working proxy connection to repeatable API checks without mixing network failures with application failures.
TL;DR
- Complete Postman proxy setup in the desktop app, then verify the exit address before testing your API.
- Keep proxy authentication separate from API authentication: a proxy login does not replace an API token.
- A diagnostic endpoint must report the peer address it actually observes; one that just echoes a client-supplied header proves nothing about the route.
- Use a stable exit for reproducible tests, and test changing exits as a separate scenario.
Proxy and API failures are different layers
A successful API response does not prove your request used the intended proxy. A bypass rule or a different execution environment can leave the request traveling through another route.
Likewise, a failed request does not prove the API rejected your credentials. Proxy authentication, tunnel establishment, TLS verification, and application authorization are separate stages. Test them separately, in that order.
Prove the route before debugging the response. For the command-line version of this process, use the curl authenticated proxy workflow.
Before you start
- Install the Postman desktop app and obtain a proxy hostname, port, authentication method, and credentials. Use an HTTP proxy endpoint for this workflow, not a SOCKS-only endpoint. If you need a low-cost HTTP endpoint to test against, Node4's shared proxies are one option; the configuration steps below are the same regardless of provider.
- Prepare an API you are authorized to test and a diagnostic endpoint that reports the caller's public address. Keep API tokens and proxy credentials separate, and use test credentials rather than production secrets.
- Check your execution environment. A browser-based request, desktop request, scheduled run, and command-line run do not automatically share the same network configuration. This guide validates local desktop requests first.
Use a diagnostic endpoint you control or trust. Its response must describe the network peer it observes, not simply repeat a client-supplied forwarding header. Otherwise, your exit-address check can pass without proving anything about routing.
Proxy configuration
Establish a known-good connection
Start outside Postman. This prevents a desktop configuration problem from being mistaken for a broken proxy account.
- Open a Bash terminal on the same machine that runs Postman.
- Enter your proxy endpoint and diagnostic URL when prompted below.
- Run the command and enter the proxy password at curl's prompt.
- Compare the reported address with your diagnostic service's direct-connection result.
read -r -p 'HTTP proxy hostname: ' PROXY_HOST
read -r -p 'HTTP proxy port: ' PROXY_PORT
read -r -p 'Proxy username: ' PROXY_USER
read -r -p 'Diagnostic HTTPS URL: ' DIAGNOSTIC_URL
curl -q --silent --show-error \
--noproxy '' \
--proxy "http://${PROXY_HOST}:${PROXY_PORT}" \
--proxy-user "$PROXY_USER" \
--connect-timeout 10 \
--max-time 30 \
--write-out '\nconnect=%{http_connect} status=%{http_code}\n' \
"$DIAGNOSTIC_URL"The connection timeout is 10 seconds; the total request limit is 30 seconds. These are example diagnostic limits for this test, not a performance claim about any provider. Increase them when your test environment requires it.
-q stops a local .curlrc from quietly adding its own proxy or bypass rule to this check. The empty bypass list in --noproxy '' then makes the request use the specified proxy rather than an inherited one. Supplying only the username lets curl prompt for the password instead of putting it directly in the command history.
%{http_connect} is the proxy's own answer to the CONNECT request: a 407 there means proxy authentication failed before the request reached the destination. %{http_code} is the diagnostic service's own response status, read separately from the connect result.
Expected result: the diagnostic service returns a response through the proxy without a proxy authentication error. A matching direct and proxied address requires investigation before you continue.
Configure the desktop proxy
Keep one intentional routing configuration active while you diagnose the connection. Do not change system routing and custom routing simultaneously.
- In Postman, open Settings, then Proxy.
- Enable Use custom proxy configuration.
- Enter the proxy hostname and port in the server configuration. Keep credentials out of the hostname field.
- Enable proxy authentication and enter the username and password supplied for that endpoint.
- Review the bypass configuration. Ensure it does not exclude either your diagnostic host or your API host.
- Return to your request workspace and create a request to the same diagnostic endpoint used with curl.
- Select GET, then Send.
Use the proxy's actual connection protocol. An HTTPS destination does not mean the proxy itself accepts TLS connections. An HTTP proxy can carry HTTPS traffic using the CONNECT method, with TLS established to the destination through that tunnel.
Do not paste a SOCKS endpoint into an HTTP proxy configuration and expect protocol conversion. Obtain a compatible endpoint or use a client that explicitly supports the required protocol.
Expected result: Postman reaches the diagnostic endpoint through the intended proxy. With a rotating service, curl and Postman can receive different exits, so exact address equality between the two clients is not a universal requirement.
Request authentication and assertions
Separate the credentials
Proxy authentication admits your connection to the proxy. API authentication identifies your request to the destination service. You often need both.
- Open the API request's Authorization tab.
- Select the authentication scheme required by the API, such as Bearer Token.
- Supply the API credential through an appropriate local secret mechanism. Do not reuse the proxy password.
- Preserve the proxy credentials in the proxy configuration, not in the request body or destination headers.
- Send a read-only request with a documented response contract.
Do not add a proxy password as an ordinary destination header. That exposes the credential to the wrong service and does not configure Postman's proxy connection.
Check the response body and headers, not just the status code. An intermediary can return an HTML error page when the API normally returns JSON. That distinction saves you from debugging the wrong authentication layer.
Expected result: the request passes proxy authentication and reaches the API's authentication stage. A successful API response then confirms both layers worked for that request.
Add a repeatable response check
Use a dedicated health or diagnostic endpoint with an explicit contract. The example below assumes that endpoint returns HTTP 200 and a nonempty JSON string named ip; adapt the assertions if your endpoint uses another schema.
- Save the diagnostic request in a collection.
- Open Scripts, then Post-response.
- Paste the assertions below.
- Select Send and inspect Test Results.
- Repeat the diagnostic request 3 times and record the observed exits alongside the results.
pm.test('Diagnostic endpoint returns HTTP 200', function () {
pm.response.to.have.status(200);
});
pm.test('Diagnostic response contains an exit address', function () {
const body = pm.response.json();
pm.expect(body.ip).to.be.a('string').and.not.empty;
});These assertions validate the response contract, not the truth of the reported address. The diagnostic service must obtain that address from its network observation. Do not treat an arbitrary ip field as independent evidence.
For a stable-exit test, compare the observed address with an expected value stored locally. For a rotating-exit test, record each address without asserting that every request must produce a new one. Rotation behavior depends on the endpoint and session configuration.
Expected result: each request produces visible test results and an exit observation. You can now distinguish a malformed diagnostic response from a proxy connection failure.
Second variant: rerun a collection after API changes
Once a single request works, use the same local desktop environment to check a collection after an API deployment or configuration change. Keep this regression workflow small enough that a failure points to a specific layer.
- Put a diagnostic request first in the collection.
- Follow it with a read-only authenticated API request.
- Add an unauthorized-request check only if the API's documented contract defines the expected result.
- Open the collection and select Run.
- Execute a local run and inspect the diagnostic result before evaluating API assertions.
Do not assume desktop proxy settings travel with an exported collection. Before moving the workflow to a CLI, CI worker, or scheduled environment, configure that environment's proxy separately and repeat the diagnostic request there.
Keep assertions specific. An API test should check the documented status and response shape, not accept any successful-looking response. Avoid automatic retries on writes unless the API provides an appropriate idempotency mechanism.
Choose the exit behavior for the test
Stable and changing exits answer different questions. Neither is a universal upgrade.
| Exit behavior | Best for | Advantage | Limitation |
|---|---|---|---|
| Stable exit | Reproducing access rules and session behavior | Removes an address change from the test variables | Does not exercise behavior across changing network identities |
| Changing exits | Testing application behavior across different source addresses | Exposes address-dependent responses | Adds variability and can disrupt address-bound sessions |
For reproducible debugging, start with a stable exit. Add changing exits only after the same request passes consistently through the baseline route.
If you use a sticky session, document its lifetime and assignment rules. A sticky setting is not a promise that an address persists indefinitely, and an expired session can invalidate an otherwise careful comparison.
Troubleshooting
Proxy returns HTTP 407
HTTP 407 means proxy authentication is required. Recheck the proxy username, password, authentication method, and endpoint before changing the API token.
Remove accidental spaces introduced by copying credentials. If curl also fails against the same endpoint, resolve that connection first. Repeatedly editing the API request will not repair proxy authentication.
API returns HTTP 401 or 403
HTTP 401 indicates missing or unacceptable authentication credentials for the responding service; HTTP 403 indicates refusal. Inspect the response to establish whether the API or an intermediary generated it.
If the API generated the response, check token scope, expiration, account permissions, and any documented source-address restrictions. A working proxy does not grant access to a protected API.
Connection times out or is refused
Check the hostname, port, protocol, local firewall, and network access rules. Retry the curl diagnostic from the same machine without changing several settings at once.
A refused TCP connection and a timeout are different observations. Record the exact error. Raising a timeout does not fix a wrong port or a blocked route.
TLS certificate verification fails
Keep certificate verification enabled. Check the destination hostname, certificate chain, system clock, and any organization-managed interception certificate.
For an authorized corporate inspection environment, install the approved certificate through the appropriate trust configuration. Do not turn a temporary verification bypass into the saved collection's normal behavior.
Response succeeds but the route is wrong
Review bypass rules and confirm which client actually executed the request. A desktop success does not establish the route of a cloud or CI execution.
Repeat the diagnostic request inside the failing environment. Also verify that the diagnostic endpoint reports the peer address rather than trusting an arbitrary forwarding header.
Customize your workflow
For your test collection, record the execution environment, endpoint configuration, authentication method, and observed exit alongside each failure. Omit passwords and tokens from screenshots, exports, logs, and issue reports.
Expand in controlled stages: a diagnostic request, a read-only API request, then the smallest collection that reproduces the behavior. Change one variable per rerun. This makes route changes distinguishable from token changes or application deployments.
When the desktop collection is reliable, move the same response contracts into your automation client. A scripted client that also authenticates to a financial API, such as a crypto exchange trading bot, needs this exact proxy-then-API authentication order, just with no desktop UI to fall back on when it fails. The Python requests session workflow is a useful next step for scripted checks; verify the route again rather than treating the port as a transparent migration.
FAQ
How do I complete Postman proxy setup with a username and password?
Configure the proxy under Settings, then Proxy, in the desktop app, and enter the proxy credentials in its authentication configuration. Send a diagnostic request before testing API authentication.
Does an HTTPS API require an HTTPS proxy endpoint?
No. An HTTP proxy can tunnel an HTTPS request using CONNECT. Configure the proxy connection according to the endpoint's actual protocol, not the destination URL alone.
Why does Postman return 407 when my API token is correct?
HTTP 407 concerns proxy authentication, not API token validation. Check the proxy credentials and authentication configuration separately from the request's Authorization tab.
Can I put my proxy password in the API Authorization tab?
No. The API Authorization tab configures authentication to the destination service. Enter proxy credentials in the proxy configuration so they are used for the proxy connection.
Will my exported collection include a working proxy setup?
Do not treat a collection export as a portable network configuration. Configure and verify the proxy independently in each desktop, CLI, CI, or scheduled execution environment.
Should my API test use a stable exit or changing exits?
Use a stable exit first when reproducing authentication, IP whitelisting tied to one address, or session behavior. Test changing exits separately so network variability does not obscure the baseline result.
How do I prove Postman is using the proxy?
Send a request to a trusted diagnostic endpoint that reports the observed peer address. Check that result against your intended route, and repeat the check in the environment that runs the actual API tests.
Check the API host's route too
An exit-address check sent to one hostname does not prove another hostname follows the same route. Bypass rules can treat the diagnostic endpoint and API differently.
Verify both hosts against the proxy configuration before calling the integration done. When you control the API, confirm the request's source address in server-side logs as well. A passing response assertion proves the response contract, not the network path.