Proxy documentation

Endpoints

Use socks5h:// so hostnames resolve through the proxy. The HTTPS port terminates TLS at the gateway with a trusted certificate — no --proxy-cacert or -k needed, and it works from networks that block plain HTTP CONNECT.

curl -x "https://ofp_0123abcd-country-de:$PASS@proxy.oneforproxy.com:8443" https://api.ipify.org

Authentication

Create a credential under Proxies. The login looks like ofp_0123abcd; the password is generated for you and can be rotated at any time. Wrong credentials return 407 Proxy Authentication Required.

Proxy-Authorization: Basic base64("ofp_0123abcd-country-de:<password>")

# curl does this for you:
curl -x "http://ofp_0123abcd-country-de:$PASS@proxy.oneforproxy.com:8080" https://api.ipify.org

IP whitelist authentication

For servers with a static IP you can skip the username/password entirely: whitelist the IP under Proxies and connect with no Proxy-Authorization header (HTTP) or the no-auth method (SOCKS5). Each IP maps to one credential and one fixed set of targeting options (country/state/city/ASN/session/life) — for varied targeting from the same machine, use a regular credential instead. Up to 10 IPs per account; anyone sharing that IP (same office NAT) can use the proxy too, so only whitelist IPs you control.

# HTTP — no Proxy-Authorization header at all, source IP is looked up instead
curl -x "http://proxy.oneforproxy.com:8080" https://api.ipify.org

# SOCKS5 — client offers only the no-auth (0x00) method
curl --socks5-hostname proxy.oneforproxy.com:1080 https://api.ipify.org

Username options

Targeting is encoded in the username as -key-value pairs, in this order. Values are lowercase; use _ instead of spaces.

<login>[-country-<cc>][-state-<x>][-city-<x>][-asn-<n>][-session-<id>][-life-<minutes>]

Targeting lists

The dashboard offers searchable country, state/region, city and carrier (ASN) dropdowns so you don’t have to guess how a place is spelled. The same lists are available as plain JSON — no authentication, no API key — if you want to build the selection into your own tooling. Codes are lowercase ASCII with no separators (california, losangeles, 3209), exactly as the username options expect them.

curl "https://oneforproxy.com/api/v1/public/geo/cities?country=us&state=california"

# 200
{ "version": "7a01eb7d3395", "country": "us", "state": "california",
  "items": [ { "code": "losangeles", "name": "Los Angeles", "state": "california" }, … ] }

# → username: ofp_0123abcd-country-us-state-california-city-losangeles

Every response carries a version field for the list snapshot and may be cached for an hour (ETag and If-None-Match are supported). A country with no entry returns an empty items array, and a missing or malformed country parameter returns 422.

The lists are a suggestion layer, not a restriction: a value that is not in them can still be used in the username or on a whitelisted IP. Availability varies by location — if a city has no IPs available right now, the connection fails with 502, so test narrow targets with the Test button on the Proxies page before a large job.

Examples

curl -x "http://ofp_0123abcd-country-de:$PASS@proxy.oneforproxy.com:8080" https://api.ipify.org

curl -x "socks5h://ofp_0123abcd-country-de:$PASS@proxy.oneforproxy.com:1080" https://api.ipify.org

import requests

proxy = "http://ofp_0123abcd-country-us-city-new_york:PASS@proxy.oneforproxy.com:8080"
r = requests.get("https://api.ipify.org?format=json",
                 proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.json())

import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent("http://ofp_0123abcd-country-de:PASS@proxy.oneforproxy.com:8080");
const res = await fetch("https://api.ipify.org", { dispatcher });
console.log(await res.text());

Sticky sessions

Add -session-<id> to pin an IP: every request with the same id reuses the same exit IP. -life-<minutes> (1–1440) sets how long the pin lasts. Use a different id per thread to get parallel sticky IPs.

# same IP for 10 minutes under session id "job42"
curl -x "http://ofp_0123abcd-country-us-session-job42-life-10:$PASS@proxy.oneforproxy.com:8080" https://api.ipify.org
curl -x "http://ofp_0123abcd-country-us-session-job42-life-10:$PASS@proxy.oneforproxy.com:8080" https://api.ipify.org   # → same IP

Errors

Management API

Everything the dashboard can do — credentials, IP whitelist, usage, wallet and monthly plans — is also available programmatically. Create a key under API keys and send it in the X-API-KEY header (never in the URL or a query string).

What is exposed

Examples

curl -X POST "https://oneforproxy.com/api/v1/proxies" \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"label": "scraper-01"}'

# 201
{ "id": 12, "login": "ofp_0123abcd", "password": "…", "label": "scraper-01", "active": true }

curl -H "X-API-KEY: $KEY" "https://oneforproxy.com/api/v1/usage/summary"

# 200 (abridged)
{ "today": { "bytes_total": 1073741824, "bytes_from_plan": 1073741824, "amount_usd": 0.0 },
  "quota_bytes_remaining": 5368709120,
  "plan_bytes_remaining": 45097156608,
  "plan_period_end": "2026-10-16T10:00:00Z",
  "price_per_gb": 3.0 }

curl -H "X-API-KEY: $KEY" -o usage.csv \
  "https://oneforproxy.com/api/v1/usage/records.csv?since=2026-09-01T00:00:00Z&until=2026-09-16T00:00:00Z"

# CSV, UTF-8 with BOM. Up to 50,000 rows; a truncated export sets X-Truncated: 1.

Errors use standard status codes: 401 invalid or revoked key, 402 no allowance left, 404 unknown id, 409 conflict (e.g. you already have a plan), 422 validation, 429 rate limited. Step-by-step walkthrough and a Python example: Management API.

Deprecated — kept working for existing integrations; new code should use GET /api/v1/wallet/balance, which returns the same balance plus the remaining plan and package allowance. Both accept the same X-API-KEY header.

curl -H "X-API-KEY: $KEY" "https://oneforproxy.com/balance"

# 200
{ "balance": 42.5, "currency": "USD", "quota_bytes_remaining": 5368709120, "price_per_gb": 3.0 }