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

Structured username controls for rotating gateways

Rotating gateway endpoints also accept structured username controls after your base username. The current v1 grammar is:

USERNAME--session-SESSION_ID--duration-SECONDS--provider-dc|res--geo-country-US

Use the base username by itself for default routed behavior. Add structured controls only when you want to pin a session, request a provider type, or constrain the route to a country. The endpoint stays the same; only the username changes.

# Default routed request
http://USERNAME:API_KEY@<ROTATING_HTTP_ENDPOINT>

# Residential US session for 90 seconds
http://USERNAME--session-cart-7--duration-90--provider-res--geo-country-us:API_KEY@<ROTATING_HTTP_ENDPOINT>

Finding your API key

1. Log in to customer.ninjasproxy.com
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. For routed gateway behavior, prefer structured username controls over guessing endpoint variants.

# 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 residential US session on a rotating gateway
http://USERNAME--session-myrun01--duration-90--provider-res--geo-country-us:API_KEY@<ROTATING_HTTP_ENDPOINT>

Routed HTTP traffic also accepts headers such as X-Session-ID, X-Session-Duration, X-Provider-Type, and X-Target-Geo. Username controls are the better default when you want the same auth string to work across HTTP and SOCKS5.

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

• Rotating proxies — routed defaults, username controls, and sticky-session examples.
• 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.