Authentication

NinjaProxy supports two authentication methods. You can use either independently or combine them. IP whitelist is checked first; if your source IP is already allowlisted, the gateway does not need credentials in the request.

Method 1 — Username + API key

Pass your portal username and API key as the proxy username and password. These values are used for proxy authentication only and are not forwarded to the target site.

Format

http://USERNAME:API_KEY@PROXY_HOST:PORT

Finding your API key

1. Log in to portal.ninjasproxy.dev
2. Open your account settings
3. Go to the API key section
4. Copy the key and store it like a password

Store secrets safely: keep your API key in an environment variable or a secrets manager. Do not hard-code it into source files or screenshots.

Assigned endpoints vs rotating gateways

The same API key works across assigned/static endpoints and rotating gateway endpoints. Use the exact endpoint shown in the portal, and add a username suffix only where that endpoint type supports it.

# Assigned/static endpoint copied from Portal → Proxy IPs
http://USERNAME:API_KEY@<HTTP_ENDPOINT>

# Rotating gateway endpoint copied from Portal → Rotating Gateway IPs
http://USERNAME:API_KEY@<ROTATING_HTTP_ENDPOINT>

# Sticky session on a rotating gateway
http://USERNAME-session-myrun01:API_KEY@<ROTATING_HTTP_ENDPOINT>

Method 2 — IP whitelist

Whitelist your server's egress IP and connect without embedding credentials. This is best when your traffic always comes from known fixed IPs.

Adding IPs to your whitelist

1. Log in to the portal
2. Open the IP whitelist settings
3. Add a single IP or CIDR block
4. Wait for the change to propagate

# Whitelisted connection — no credentials needed
curl --proxy "http://<HTTP_ENDPOINT>" "https://ip.ninjasproxy.com/"

# Python with no credentials
proxies = {
    "http":  "http://<HTTP_ENDPOINT>",
    "https": "http://<HTTP_ENDPOINT>",
}
r = requests.get("https://ip.ninjasproxy.com/", proxies=proxies)

IP whitelist uses your source IP for auth. If you are using a rotating gateway endpoint that supports routing hints in the username, keep those hints in the username but still use the exact endpoint from the portal.

Common auth errors

Special characters in credentials

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

import urllib.parse

username = "myuser"
api_key  = "p@ss:word/123"
endpoint = "203.0.113.10:3128"  # Copy from Portal → Proxy IPs

encoded_key = urllib.parse.quote(api_key, safe="")
proxy_url = f"http://{username}:{encoded_key}@{endpoint}"
print(proxy_url)
# http://myuser:p%40ss%3Aword%[email protected]:3128

Next Steps

• Rate Limits — concurrency, balance behavior, and retries.
• Residential proxies — assigned endpoint behavior.
• Python integration — session management and retry logic.
• API Reference — token, account, usage, and endpoint APIs.