Proxy Provider API Integration: Auto-Provision Multi-Account Browser Profiles at Scale
Copying proxy credentials into profiles by hand stops working well before a few hundred profiles. Wiring your proxy provider's endpoints into code does the binding instead.
That's what this tutorial covers: wiring proxy-provider endpoints into JustBrowser's profile management. Not manual config. Not GUI clicking. Profiles created from a script, each with its own proxy already attached.
(Fair warning: the code examples are a starting point. You'll want to refactor.)
What We're Building
By the end of this, you'll have:
- A script that generates sticky-session endpoints for common proxy providers (Bright Data, Oxylabs, IPRoyal patterns)
- A client for JustBrowser's local REST API that creates and configures profiles
- A provisioning workflow that gives each new profile its own proxy
- A replacement routine for proxies that stop responding
This is the engineering approach to multi-account infrastructure: agencies running client accounts, QA teams testing from several regions, ad-verification teams checking how a page renders by geography. Everything below assumes you hold the accounts legitimately and operate within each platform's terms.
Prerequisites
- A JustBrowser subscription ($9.99/month or $99.99/year, with a 7-day free trial that needs a card). REST API access comes with the plan, there's no separate API tier. Team seats don't get API access.
- A proxy provider. Bring your own (Bright Data, Oxylabs, IPRoyal, Smartproxy), or buy a proxy plan inside the app. Proxies aren't included in the subscription.
- Node.js 18+ or Python 3.10+ (examples in both)
- Basic REST API familiarity. You know what a Bearer token is.
For manual proxy setup basics, see the ISP proxy configuration guide. This tutorial assumes you've got that foundation and want to automate.
Step 1: Get Your Proxy Provider Credentials
Each provider structures access differently, and they change dashboards often. Treat what follows as a map, then confirm against the provider's current docs.
Bright Data
In the dashboard you'll typically find a customer ID (format brd-customer-XXXXX), a zone name for your ISP or residential pool, and a zone password. Sticky sessions are requested by adding a session parameter to the proxy username.
Oxylabs
Oxylabs is simpler: a username and password. Session stickiness is again string-based. You build the proxy username with session parameters rather than calling an API for each IP.
IPRoyal
IPRoyal offers an account API, but for rotating residential traffic the sticky behaviour comes from parameters appended to the password string.
Smartproxy
Smartproxy gives you sub-user management and endpoint generation from the dashboard.
Honest frustration: every provider uses a different separator, a different parameter order and a different session lifetime syntax. None of it is hard, but a single typo gives you a working-looking proxy that rotates every request. Test one endpoint by hand before you generate fifty.
Step 2: Generate Sticky Endpoints Programmatically
The goal: a unique sticky-session endpoint for each profile. Most providers do this through a session identifier in the connection string.
A Node.js function for Bright Data-style endpoints:
// bright-data-provisioner.js
const BRIGHT_DATA_CUSTOMER = 'brd-customer-XXXXX';
const BRIGHT_DATA_ZONE = 'isp_residential'; // your zone name
const BRIGHT_DATA_PASSWORD = 'YOUR_ZONE_PASSWORD';
export function generateBrightDataEndpoint(profileId, country = 'us') {
// Session ID tied to profile: same session = same IP
const sessionId = `profile-${profileId}-${Date.now()}`;
const username = `${BRIGHT_DATA_CUSTOMER}-zone-${BRIGHT_DATA_ZONE}-country-${country}-session-${sessionId}`;
const host = 'brd.superproxy.io';
const port = 22225;
return {
protocol: 'http',
host,
port,
username,
password: BRIGHT_DATA_PASSWORD
};
}
The -session- parameter is what makes this sticky. The gateway assigns an IP when the session ID is first used and keeps returning it until the session expires. Session lifetime varies by product, so check yours.
For Oxylabs the pattern is similar and the format differs:
// oxylabs-provisioner.js
const OXYLABS_USERNAME = 'customer-XXXXX';
const OXYLABS_PASSWORD = 'YOUR_PASSWORD';
function generateOxylabsEndpoint(profileId, country = 'us') {
const sessionId = `profile${profileId}`;
const username = `${OXYLABS_USERNAME}-cc-${country}-sessid-${sessionId}`;
const host = 'pr.oxylabs.io';
const port = 7777;
return {
protocol: 'http',
host,
port,
username,
password: OXYLABS_PASSWORD
};
}
And IPRoyal, where the session lives in the password:
// iproyal-provisioner.js
function generateIPRoyalEndpoint(profileId) {
const sessionId = `jb-${profileId}`;
return {
protocol: 'http',
host: 'geo.iproyal.com',
port: 12321,
username: 'YOUR_USERNAME',
password: `YOUR_PASSWORD_country-us_session-${sessionId}_lifetime-24h`
};
}
The hosts, ports and parameter names above are illustrative. Copy the real ones from your provider's dashboard.
The idea is the same everywhere: embed a session identifier you control, map it to your profile ID, and let the provider handle IP persistence. Session-based sticky is the boring solution. Boring is fine here.
Step 3: Connect to JustBrowser's REST API
JustBrowser's REST API is local only. It's bound to 127.0.0.1, and there's no hosted endpoint to call instead. The default port is 36542, configurable in the app. Authentication is a Bearer token from the AI page in the app, available on a subscription or trial. The full reference lives at justbrowser.app/docs, generated from the app's real routes, so check field names there rather than trusting any snippet, including these.
The shape matters more than the syntax. Proxies are their own objects. You create a proxy with POST /proxies, then attach it to a profile with PUT /profiles/{id}/proxy. POST /profiles itself takes no proxy field.
// justbrowser-client.js
const API_BASE = 'http://127.0.0.1:36542/api/v1';
const TOKEN = process.env.JUSTBROWSER_TOKEN;
const headers = {
'Content-Type': 'application/json',
Authorization: `Bearer ${TOKEN}`
};
async function call(method, path, body) {
const res = await fetch(`${API_BASE}${path}`, {
method,
headers,
body: body ? JSON.stringify(body) : undefined
});
const json = await res.json();
if (!res.ok) {
// Branch on error.code, never on the message text
throw new Error(`${json.error?.code}: ${JSON.stringify(json.error?.details ?? json.error?.message)}`);
}
return json.data;
}
export function listProfiles() {
return call('GET', '/profiles');
}
// Proxy body: protocol (http | https | socks5), host and port are required.
// The port must be an integer.
export function createProxy(name, proxyConfig) {
return call('POST', '/proxies', {
name,
protocol: proxyConfig.protocol,
host: proxyConfig.host,
port: proxyConfig.port,
username: proxyConfig.username,
password: proxyConfig.password
});
}
// POST /profiles accepts name, folder_id, notes, os, browser, locale, device_type
export function createProfile(name, options = {}) {
return call('POST', '/profiles', { name, ...options });
}
// Pass proxyId = null to take the proxy off
export function assignProxy(profileId, proxyId) {
return call('PUT', `/profiles/${profileId}/proxy`, { proxy_id: proxyId });
}
// Match the profile's time zone and language to where the proxy exits.
// apply: true writes the suggestion; omit it to preview.
export function geoMatch(profileId, proxyId) {
return call('POST', `/profiles/${profileId}/geo-match`, { proxy_id: proxyId, apply: true });
}
Responses and errors come in envelopes: success lives under data, failure under error. VALIDATION_ERROR carries details as an array of issues, which is why the helper above prints it.
Two things worth knowing. Proxy credentials are encrypted on write and never read back over the API, so keep your own record of what you sent. And bulk creation exists too, up to 100 profiles per call from a naming pattern, with POST /profiles/batch/proxy to spread a pool of proxy ids across several profiles. There's no CSV importer, so a script like this one is how you create profiles from your own list.
Step 4: Build the Auto-Provisioning Workflow
Profile creation has no time zone field (it does take a locale), and that's fine: the geo-match route reads where the proxy actually exits and suggests a matching time zone and language, which beats hard-coding America/New_York and hoping the country lines up.
A script that creates N profiles, each with its own sticky proxy:
// provision-profiles.js
import { generateBrightDataEndpoint } from './bright-data-provisioner.js';
import { createProfile, createProxy, assignProxy, geoMatch } from './justbrowser-client.js';
import { writeFile } from 'node:fs/promises';
async function provisionProfiles(count, namePrefix = 'client', country = 'us') {
const results = [];
for (let i = 0; i < count; i++) {
const profileName = `${namePrefix}-${country}-${String(i).padStart(3, '0')}`;
const proxyConfig = generateBrightDataEndpoint(profileName, country);
const proxy = await createProxy(profileName, proxyConfig);
const profile = await createProfile(profileName);
await assignProxy(profile.id, proxy.id);
await geoMatch(profile.id, proxy.id);
results.push({
profileId: profile.id,
proxyId: proxy.id,
name: profileName,
proxyHost: proxyConfig.host
});
console.log(`Created: ${profileName} → ${proxyConfig.host}`);
// Small pause between calls
await new Promise(r => setTimeout(r, 100));
}
return results;
}
const results = await provisionProfiles(50, 'client', 'us');
console.log(`Provisioned ${results.length} profiles`);
await writeFile('provisioned.json', JSON.stringify(results, null, 2));
Run it once and you've got 50 profiles, each with its own sticky endpoint, ready to launch. Remember that starting a profile through the API runs it headless unless you send {"headless": false}.
Python version of the same logic:
# provision_profiles.py
import httpx
import json
import os
import time
API_BASE = "http://127.0.0.1:36542/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['JUSTBROWSER_TOKEN']}"}
def generate_bright_data_endpoint(profile_id: str, country: str = "us") -> dict:
session_id = f"profile-{profile_id}-{int(time.time())}"
return {
"protocol": "http",
"host": "brd.superproxy.io",
"port": 22225,
"username": f"brd-customer-XXXXX-zone-isp_residential-country-{country}-session-{session_id}",
"password": "YOUR_ZONE_PASSWORD"
}
def call(client: httpx.Client, method: str, path: str, body: dict | None = None) -> dict:
res = client.request(method, f"{API_BASE}{path}", json=body)
payload = res.json()
if res.is_error:
# Branch on error.code, not the message
raise RuntimeError(f"{payload['error'].get('code')}: {payload['error'].get('details')}")
return payload["data"]
def provision_batch(count: int, prefix: str = "client", country: str = "us"):
results = []
with httpx.Client(headers=HEADERS) as client:
for i in range(count):
name = f"{prefix}-{country}-{i:03d}"
proxy_cfg = generate_bright_data_endpoint(name, country)
proxy = call(client, "POST", "/proxies", {"name": name, **proxy_cfg})
profile = call(client, "POST", "/profiles", {"name": name})
call(client, "PUT", f"/profiles/{profile['id']}/proxy", {"proxy_id": proxy["id"]})
call(client, "POST", f"/profiles/{profile['id']}/geo-match",
{"proxy_id": proxy["id"], "apply": True})
results.append({"profile_id": profile["id"], "proxy_id": proxy["id"], "name": name})
print(f"Created: {name}")
time.sleep(0.1)
return results
if __name__ == "__main__":
profiles = provision_batch(50, "client", "us")
with open("provisioned.json", "w") as f:
json.dump(profiles, f, indent=2)
Step 5: Replace Proxies That Stop Working
Proxies die. Sessions expire, IPs get recycled, a provider has a bad afternoon. Your provisioning system should handle replacement without you babysitting it. The replacement is two calls: create a fresh proxy object, then point the profile at it.
// replace-proxy.js
import { generateBrightDataEndpoint } from './bright-data-provisioner.js';
import { createProxy, assignProxy, geoMatch } from './justbrowser-client.js';
async function replaceProxy(profileId, country = 'us') {
// New session ID → new IP
const config = generateBrightDataEndpoint(`${profileId}-r${Date.now()}`, country);
const proxy = await createProxy(`${profileId}-r${Date.now()}`, config);
await assignProxy(profileId, proxy.id);
await geoMatch(profileId, proxy.id);
console.log(`Replaced proxy for profile ${profileId}`);
return proxy;
}
async function replaceMultiple(profileIds) {
const results = [];
for (const pid of profileIds) {
try {
const proxy = await replaceProxy(pid);
results.push({ profileId: pid, status: 'replaced', proxyId: proxy.id });
} catch (err) {
results.push({ profileId: pid, status: 'failed', error: err.message });
}
}
return results;
}
You can also check a proxy before trusting it: POST /proxies/{id}/test and GET /proxies/{id}/geo report whether it connects and where it exits. Old proxy objects pile up, so DELETE /proxies/{id} once a profile has moved off one.
Trigger replacement by hand or wire it to your own health check: repeated timeouts, 407 responses, or a latency number you've decided is too high. A profile's own health score in the app is a useful second signal, and you can poll GET /profiles/{id}/status for its state. There are no webhooks, so polling is the only option.
For driving these profiles from Playwright or Puppeteer, the REST API and CDP automation guide covers the connection pattern. Your framework attaches to the profile's cdp_url; the proxy binding is already done. Attach to the existing context rather than creating a new one, because a new context sits outside the profile.
Common Errors and How to Fix Them
Error: 407 Proxy Authentication Required from the proxy provider
Credentials are wrong or expired. Re-check the customer ID, zone name and zone password against the provider dashboard.
Error: Proxy creation fails with a validation error
The POST /proxies body doesn't match what the API expects. Common causes:
- Port sent as a string instead of an integer
- Wrong
protocolvalue (http,httpsorsocks5)
VALIDATION_ERROR carries details as an array of issues, so read it; it usually names the field.
Error: Same IP on multiple profiles
Your session IDs aren't unique. If two profiles share -session-profile001, they get the same IP. Append a timestamp or UUID.
Error: Provider rate limiting your calls
Slow down. Limits differ by provider and plan, so look up yours and add delays between calls.
Error: IP location doesn't match the profile's timezone
A profile set to America/New_York behind a -country-de proxy is an inconsistent setup, and sites that localize content will show you the wrong thing. Call POST /profiles/{id}/geo-match after every proxy change, as the scripts above do, so time zone and language follow the exit country.
Next Steps
You've got API-driven provisioning working. Some ways to extend it:
- Usage tracking: Log which proxies fail most often. If one provider's pool keeps timing out, that's a purchasing signal.
- Click quality: If the profiles run ad campaigns, ClickzProtect is one place to check which clicks look automated, whatever proxy they came through.
- Multi-provider fallback: If one provider's US pool is depleted, fall back to another. Same pattern, different endpoint generator.
- Cost tracking: Log bandwidth per profile. Some providers charge per GB, and knowing which profiles use the most tells you which workflows are worth their cost.
The manual era is over for anyone past a few dozen profiles. Automate the boring parts and keep your attention for the problems a script can't solve.
Frequently Asked Questions
Why use proxy provider endpoints instead of manual proxy configuration?
Manual configuration works for 5 profiles. At 50 or 500, you need automation. Session-based sticky endpoints let you generate one proxy per profile in code, bind it through the local REST API, and swap it when a proxy stops working, without touching a GUI.
Do all proxy providers offer sticky sessions?
Most residential and ISP providers do, but the mechanism differs. Some generate sticky endpoints from a session string in the username, others expose management APIs. Read your provider's current documentation before copying any format.
How do I handle a proxy that stops working?
Build replacement into your provisioning script. When a profile's proxy starts failing (timeouts, repeated 407 or 5xx responses), request a new sticky endpoint from your provider, update the profile through JustBrowser's local REST API, and log the old session for your records.
Does provisioning through the API slow down browsing?
No. Provisioning is a one-time step per profile. Once the proxy is bound, the profile connects the way it would with a proxy you typed in by hand. Check your provider's documented rate limits before you parallelize calls.
Try JustBrowser
A multi-account browser for teams, built on a custom Chromium engine with native C++ integration, not an extension, and patched on every upstream Chromium release. Real C++ engine patches at the canvas / WebGL / audio / font / screen layer, with 40+ identity parameters per profile. REST API plus CDP for Playwright, Puppeteer and Selenium. 7-day free trial, card required, then $9.99/month or $99.99/year, unlimited profiles, free team seats.
Get started → · How it differs from Multilogin / GoLogin / AdsPower
Ready to manage multiple accounts?
Seven days free, then $9.99/month — one plan, everything included.