Change language
English
Menu
Pricing
Proxies
Solutions
Resources

Proxy Authentication: Username and Password or an IP Allowlist

Contents
  1. How does a proxy know a request is yours?
  2. When is a username and password simpler?
  3. When is an IP allowlist simpler?
  4. How do you set up each method?
  5. What errors does each method produce?
  6. How do you keep proxy credentials safe?
  7. When is a ProxyJam proxy the wrong fit?
  8. Quick answers

In short: A proxy recognises you by a username and password, or by the address you connect from, checked against an IP allowlist. A password works from any network, so it suits laptops and people who move. An allowlist keeps the secret off the client, so it suits servers with a fixed address and tools that cannot send a password, such as Chrome over SOCKS5. On a ProxyJam order, a non-empty allowlist switches the password off.

A proxy has to know that a connection is yours before it forwards it. There are two ways to tell it: send a username and password, or connect from an address the proxy already knows. Both are called proxy authentication, and they fail in different places. This guide shows when each is the simpler choice, how to set each one up in a browser, in Python requests, in Selenium and in Playwright, and which error each mistake produces.

How does a proxy know a request is yours?

By what the client sends with the connection, or by the address the connection comes from.

With a username and password, the proxy answers a request that carries no credentials with status 407, Proxy Authentication Required. Your client then sends it again with a Proxy-Authorization header, as RFC 9110 describes. SOCKS5 has a sign-in of its own, defined in RFC 1929, which a client has to implement separately.

With an IP allowlist, the proxy compares the address a connection arrives from with a list you gave it. A listed address gets through with no credentials. Any other address is refused. This is the proxy’s own list. The reverse case, where your systems admit only a few addresses and the proxy supplies one of them, is covered in a static IP for IP allowlisting.

Every static IP you buy from ProxyJam has its own host, port, username and password, shown under My Proxies in the dashboard. An order starts on the password. You can give it an allowlist of IPv4 addresses instead, and while the list holds an address the password stops working for that order. Sending an empty list turns the password back on. The two methods take turns on one order, so pick per order, or keep one order per method.

When is a username and password simpler?

If the machine that connects does not keep one public address, a password is the easier choice. Most home connections get their address from the internet provider and can receive a new one after a router restart. A laptop takes a different address in every café, office and hotel, and a phone hotspot often shares one address among many subscribers. An allowlist would have to follow every one of those changes by hand, and each change locks you out until you update it.

A password goes wherever the client goes. It also suits a team spread over several cities, because nobody has to report their address before they can work. The cost is the secret itself: it has to be stored somewhere, it can be copied, and everyone who has it uses the same login.

When is an IP allowlist simpler?

An allowlist is simpler if the client has a fixed public address, or cannot send a password at all.

A server or a CI runner with a fixed public address is the plain case. The proxy admits it, and no credentials sit in its configuration, its logs or its command history.

The second case is a tool that cannot answer a password prompt:

  • Chrome and Edge over SOCKS5. Chromium’s proxy notes say no authentication method is supported for SOCKS5 in Chrome, so a SOCKS5 password is never sent.
  • Selenium driving Chrome. Chrome drops credentials written into --proxy-server, and in our tests both WebDriver BiDi handlers timed out.
  • Playwright over SOCKS5. All three engines refuse to launch with a SOCKS5 username and password.

Two limits come with it. Hosted CI runners often leave from a different address on each run, so check what yours does before you rely on it. And the proxy sees only the address, so everyone who shares it gets in: every device behind an office router, or every customer behind a provider’s shared address. List only addresses whose users you know, and remove an entry the day it stops being yours.

How do you set up each method?

The four values are the same everywhere: host, port, and either a username and password or nothing at all. Only the place they go differs. Our integration guides carry tested code for each tool; the short versions follow.

In Chrome, Edge or Firefox with ProxyJam Connector

Chrome reads no credentials from its proxy settings and asks in a dialog instead. ProxyJam Connector, our free extension, answers that dialog for you. Sign in to your ProxyJam account in it and press Connect beside a proxy, or add a profile by hand with the host, port, username and password. On Chrome and Edge it answers once you grant network access on its Settings page.

For an allowlist, open the proxy’s Manage dialog in the extension and fill in Allowed IP addresses, one per line. Leaving the field empty returns the order to its username and password.

In Python requests

requests takes the credentials inside the proxy URL. Keep them out of the script and read them from the environment:

import os
from urllib.parse import quote

import requests

user = os.environ["PROXY_USER"]
password = quote(os.environ["PROXY_PASSWORD"], safe="")
proxy = "http://" + user + ":" + password + "@HOST:PORT"

r = requests.get("https://example.com/", proxies={"http": proxy, "https": proxy}, timeout=30)

quote matters when the password holds a slash, a question mark, a hash or a percent sign, which would otherwise break the URL. With an allowlist the URL is just http://HOST:PORT. The requests guide adds sessions, and SOCKS5 with the proxy resolving hostnames.

In Selenium

For Chrome, use the allowlist and pass the address without credentials:

from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--proxy-server=http://HOST:PORT")
driver = webdriver.Chrome(options=options)

Firefox under Selenium can send a username and password through a WebDriver BiDi authentication handler. The Selenium guide has both samples, with the versions we tested them on.

In Playwright

Playwright takes the username and password in fields of their own, never inside the server URL:

browser = playwright.chromium.launch(proxy=dict(
    server="http://HOST:PORT",
    username=os.environ["PROXY_USER"],
    password=os.environ["PROXY_PASSWORD"],
))

Over SOCKS5, pass only server="socks5://HOST:PORT" and use the allowlist. The Playwright guide covers a proxy per context and the results for all three engines.

What errors does each method produce?

A rejected password and a missing one look alike: the proxy answers 407. How that reaches you depends on the client.

  • Chrome shows its sign-in dialog, and shows it again after each rejected attempt. The post on why Chrome keeps asking for proxy credentials explains the loop.
  • ProxyJam Connector stops after the proxy rejects the stored credentials twice for one request, and its toolbar badge shows AUTH.
  • requests returns a response with status 407 for an http:// address. For an https:// address the tunnel through the proxy fails, and requests raises a ProxyError whose message carries the 407.
  • Selenium with Chrome loads no page when the credentials sit in --proxy-server, which reads like a network fault.
  • Playwright with credentials written into the server URL hung on its first navigation in our test, with no message about the password.

An allowlist fails in its own ways:

  • The address changed. A new public address is not on the list, so the proxy refuses the connection. Look the address up again and update the list.
  • The list was set, and another client still uses the password. Setting the allowlist for a server switches the password off for the whole order, laptops included. Keep those clients on a second order, or add their addresses too.
  • The list was replaced by accident. Each call sends the full list, so an update that names only the new address drops the old ones.

How do you keep proxy credentials safe?

Treat the proxy password like any other password. Keep it out of the code and out of the repository: read it from an environment variable or a secrets manager, as the Twelve-Factor App and the OWASP secrets cheat sheet recommend. A proxy URL with a password in it ends up in logs, crash reports and shell history, so print the host and port, never the whole URL.

The API key is a separate secret and a larger one. It reaches your account, and a key with the right scope can spend from your wallet. Give each script or teammate a key of its own, so that removing one leaves the others working. Delete a key on the API Keys page of the dashboard the day the person or script that used it leaves.

The proxy password is harder to take back. Our API reference lists no call that changes it for a static residential (ISP) proxy. If someone who knew it leaves, the lever you hold is the allowlist: set it to the addresses you still use, and the old password stops working for that order.

When is a ProxyJam proxy the wrong fit?

It is the wrong fit if you need a separate login for each person on one address. Each static IP has one username and one password, so per-person access means one address per person, or an allowlist entry per person’s fixed address.

It also does not fit work that needs a new address for every request. That takes a rotating pool, and ProxyJam does not sell one today. What we sell is static residential (ISP) proxies: one address on a named internet provider’s network, yours for the period you pay for, with prices on the pricing page. If you already have one, using your static IP after purchase shows where its details are in the dashboard.

Pick a method for each place you connect from

Verdicts follow how ProxyJam orders authenticate, Chromium's proxy notes, and the tests on our integration pages, run on 2026-10-22 with Selenium 4.51 and Playwright 1.64 against a local proxy. We did not test every version of every client, and a later release can change what a browser accepts.
Username and passwordIP allowlist
A laptop that changes networksWorks from every networkFails each time the public address changes
A server or CI runner with a fixed public IPv4 addressWorks; the secret has to be stored on the machineWorks with no secret on the machine
Chrome or Edge over HTTPWorks through the sign-in dialog or an extensionWorks with no dialog
Chrome or Edge over SOCKS5Fails; Chrome sends no SOCKS5 passwordWorks
Selenium driving ChromeFailed in our testWorks
Playwright, any engineWorks over HTTP; refused at launch over SOCKS5Works over HTTP and SOCKS5
Python requestsWorks over HTTP and SOCKS5Works over HTTP and SOCKS5
Several people on one orderEveryone shares one passwordOne entry per address; everyone behind a listed address gets in

Move an order from a password to an allowlist

  1. Find the public address you connect from

    Open What Is My IP on the machine that will use the proxy, with no proxy on. The address it shows is the one the proxy will see. A server or CI runner has to look it up from the machine itself.

  2. Add it to the allowlist

    In ProxyJam Connector, open the proxy’s Manage dialog and type the address into Allowed IP addresses, one per line. From code, send PUT /orders/ORDER_ID/whitelist with the full list; each call replaces the previous one.

  3. Remove the credentials from every client of that order

    Give the client only http://HOST:PORT, or socks5://HOST:PORT after switching the order to SOCKS5. Any client that still relies on the password stops connecting now, because the password no longer works for this order.

  4. Check the exit address

    Load What Is My IP again, this time through the proxy. It should show the static address you bought.

  5. Clear the list to go back

    An empty list turns the allowlist off, and the username and password work again.

Quick answers

Is an IP whitelist the same thing as an IP allowlist?

Yes. Both names mean a list of client addresses a proxy admits without a password. Allowlist is the newer word. Our API keeps the older one in its identifiers, such as the endpoint PUT /orders/ORDER_ID/whitelist and the field whitelisted_ips.

Can I use a password and an allowlist on the same ProxyJam order?

No. While the allowlist holds at least one address, the proxy admits only the listed addresses and the username and password stop working for that order. Sending an empty list turns the allowlist off and password sign-in works again.

Where do I set the allowlist for a ProxyJam proxy?

In ProxyJam Connector, in the Allowed IP addresses field of the proxy's Manage dialog; through the API, with PUT /orders/ORDER_ID/whitelist; or with the set_proxy_whitelist tool of our MCP server. The dashboard has no control for it yet. Integrations

What does error 407 mean?

407 Proxy Authentication Required means the proxy wants credentials before it forwards the request, as RFC 9110 defines it. A client that sent none, sent them where the proxy does not look, or sent wrong ones gets the same answer. Proxy password prompt

Why does Chrome not use the password in my SOCKS5 proxy settings?

Chrome implements no SOCKS5 authentication, so it cannot send a SOCKS5 username and password. Put the address you connect from on the proxy's allowlist, use the proxy over HTTP, or use Firefox, which passes SOCKS5 credentials to the proxy. Browser Extension

Can I change the password of my ProxyJam proxy?

The API reference lists no call that changes the password of a static residential (ISP) proxy. What you control is the allowlist: setting it to the addresses you still use switches the password off for that order.

Sources