Authentication

NinjasProxy supports two authentication methods. You can use either independently or combine them — IP whitelist is checked first; if your IP is whitelisted, no credential check is performed.

Method	Best for	Credentials in requests?
Username + API key	Dynamic IPs, cloud VMs, serverless	Yes — embedded in proxy URL
IP whitelist	Fixed-IP servers, scraping clusters	No — connection is pre-authorised

Method 1 — Username & API Key

Pass your portal username and API key as the proxy username and password. These are transmitted in the HTTP Proxy-Authorization header and are never forwarded to the target server.

Format

http://USERNAME:API_KEY@PROXY_HOST:PORT

Finding your API key

Log in to portal.ninjasproxy.com
Click your avatar → Settings
Navigate to the API Key tab
Copy the key — treat it as a password; never commit it to source control

Regenerating your API key

In Settings → API Key click Regenerate. This immediately invalidates the old key. Update all services before regenerating to avoid downtime.

Store your API key in an environment variable (NINJASPROXY_API_KEY) or a secrets manager. Never hard-code it in source files.

Rotating vs. static credentials

The same API key works for both rotating and sticky-session proxies — the mode is controlled by the username suffix, not a separate credential:

# Rotating — new IP every request
http://USERNAME:API_KEY@r.ninjasproxy.com:8080

# Sticky — same IP for up to 60 min
http://USERNAME-session-myrun01:API_KEY@r.ninjasproxy.com:8080

# Geo-targeted + sticky
http://USERNAME-country-US-city-Chicago-session-chi01:API_KEY@r.ninjasproxy.com:8080

Method 2 — IP Whitelist

Whitelist your server's egress IP(s) and connect to the proxy without any username or password. The proxy gateway recognises your source IP and authorises the connection automatically.

Adding IPs to your whitelist

Log in to the portal
Go to Settings → IP Whitelist
Click Add IP — enter a single IPv4/IPv6 address or a CIDR block (e.g. 203.0.113.0/24)
Changes take effect within 30 seconds

# Whitelisted connection — no credentials needed
curl --proxy "http://r.ninjasproxy.com:8080" "https://api.ipify.org?format=json"

# Python with no credentials
proxies = {
    "http":  "http://r.ninjasproxy.com:8080",
    "https": "http://r.ninjasproxy.com:8080",
}
r = requests.get("https://api.ipify.org?format=json", proxies=proxies)

IP whitelist does not support targeting parameters (country, session, etc.). For geo-targeted or session-pinned requests from a whitelisted IP, include the targeting in the username even without a password: http://USERNAME-country-US@r.ninjasproxy.com:8080 — the gateway uses the whitelist for auth and the username for routing.

Common Auth Errors

HTTP Status	Meaning	Fix
407 Proxy Authentication Required	Missing or malformed credentials	Ensure USERNAME:API_KEY are URL-encoded; check for special characters in your key
401 Unauthorized	Credentials present but invalid	Verify your API key in the portal — it may have been regenerated
403 Forbidden	IP not whitelisted (whitelist mode)	Add your egress IP in Settings → IP Whitelist
402 Payment Required	Balance exhausted	Top up balance in the portal Billing page

Special characters in credentials

If your API key contains characters like @, :, or /, percent-encode them when embedding in a URL:

import urllib.parse

username = "myuser"
api_key  = "p@ss:word/123"

encoded_key = urllib.parse.quote(api_key, safe="")
proxy_url = f"http://{username}:{encoded_key}@r.ninjasproxy.com:8080"
print(proxy_url)
# http://myuser:p%40ss%3Aword%2F123@r.ninjasproxy.com:8080

Next Steps

Rate limits — concurrent connections and balance behaviour
Residential proxies — targeting format reference
Python integration — session management and retry logic
API Reference — regenerate credentials programmatically