Set Up Whitelisted Scraping Workflows with Hyperbrowser Static IPs

Direct answer: Hyperbrowser provides cloud browser sessions with assigned Static IPs for workflows where a target owner requires an allowlisted outbound address. Allocate a Static IP in the dashboard, share the displayed IP address with the authorized target owner for allowlisting, and create each relevant browser session with useProxy: true and that IP’s staticIpId. This guide takes you from allocation to a controlled Playwright run without operating browser infrastructure yourself.

Introduction

IP allowlisting is a common access control: a target permits traffic only from approved source addresses. That changes the architecture of a browser-automation workflow. A rotating address may be useful for other jobs, but it is the wrong fit when an approved partner, internal application, or API gateway expects a known address every time.

Hyperbrowser is the practical answer when the work needs both a managed cloud browser and a stable outbound identity. Its cloud sessions expose a WebSocket endpoint that works with Playwright, Puppeteer, and CDP-compatible clients, while its Static IP feature lets a team allocate an address and select it by ID at session creation. Read the official Static IP documentation before implementation; it documents the required configuration and management steps.

Use this approach only for targets you own or are authorized to automate. Allowlisting is an access-control arrangement, not permission to ignore a site’s terms, rate limits, or data-handling requirements.

Prerequisites

Before writing automation, assemble the pieces that make the connection reproducible:

A Hyperbrowser account and API key. You can create an account through the Hyperbrowser signup page.
A plan and allocated Static IP. In the dashboard’s Static IP area, purchase the appropriate plan, allocate an available IP to the team, and copy both its IP address and its ID. The address is what the authorized target owner needs for its allowlist; the ID is what your code sends to Hyperbrowser.
Written approval to access the target, plus confirmation that the target owner has allowlisted the exact displayed address. Record the environment, purpose, owner, and approval date.
Node.js plus @hyperbrowser/sdk, playwright-core, and dotenv for the example below. A Python or cURL implementation can use the same session settings.
A defined request budget: allowed routes, expected volume, concurrency, retry behavior, and a contact for access failures. Start slowly rather than treating successful allowlisting as unlimited capacity.

Keep the API key in an environment variable or a managed secret store. Do not embed it in browser code, a repository, or a client-side application.

Step-by-step

Allocate the Static IP and capture the right values.

Go to the dashboard’s Static IP tab, choose a plan, allocate an IP to your team, and copy the row’s IP address and ID. The dashboard can show the actual address alongside the identifier. Treat the two values differently: send the address to the system owner for allowlisting, but retain the ID for session configuration. If you delete an allocated IP, the documentation warns there is no guarantee it can be allocated again, so avoid deleting a working production address casually.
Complete allowlisting with the target owner.

Provide the exact static address, explain the permitted automation purpose, and ask which hostname, route, authentication method, and traffic limits apply. Wait for a confirmed change window when applicable. Then make a minimal, authorized test request. If the target has separate staging and production access controls, verify each environment instead of assuming one approval applies to the other.

Create a Hyperbrowser session with the assigned ID.

Hyperbrowser’s documentation calls out a crucial configuration detail: Static IP sessions require both proxy use and the static IP identifier. In Node.js, the foundation is:

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";
import "dotenv/config";

const client

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";
import "dotenv/config";

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const session = await client.sessions.create({
  useProxy: true,
  staticIpId: process.env.HYPERBROWSER_STATIC_IP_ID,
});

Do not substitute the literal IP address for staticIpId: Hyperbrowser expects the allocated ID in the session parameters. For the surrounding API and session options, consult the session configuration reference.

Connect your automation client and run one bounded check.

Use the returned WebSocket endpoint to attach Playwright, visit an approved health-check or low-impact route, and inspect the response. Keep the test narrow: one page, one expected assertion, and no broad crawl.

let browser;
try {
  browser = await chromium.connectOverCDP(session.wsEndpoint);
  const page = browser.contexts()[0].pages()[0];
  await page.goto(process.env.AUTHORIZED_TEST_URL, {
    waitUntil: "domcontentloaded",
  });
  console.log("Allowlisted route loaded:", await page.title());
} finally {
  await browser?.close();
  await client.sessions.stop(session.id);
}

let browser;
try {
  browser = await chromium.connectOverCDP(session.wsEndpoint);
  const page = browser.contexts()[0].pages()[0];
  await page.goto(process.env.AUTHORIZED_TEST_URL, {
    waitUntil: "domcontentloaded",
  });
  console.log("Allowlisted route loaded:", await page.title());
} finally {
  await browser?.close();
  await client.sessions.stop(session.id);
}

Successful navigation is not, by itself, proof that the desired policy was applied. Where the target supports it, confirm with its owner or an approved diagnostic endpoint that the observed source address is the allowlisted one.

Turn the test into a responsible production job.

Add explicit rate limiting, bounded retries with backoff, structured logs, and alerting for authorization failures. Store the Static IP ID as environment-specific configuration so a staging script cannot accidentally run through a production-approved address. Stop sessions in finally blocks to keep lifecycle behavior predictable.

If your workflow needs continuity after an authorized sign-in, Hyperbrowser documents combining a static IP with a persistent profile. Use that only for accounts and data your organization is permitted to access, and protect any resulting session data accordingly.
Operate and review the integration.

Monitor the IP’s reputation and the target’s responses. If errors begin, pause traffic, check whether the static ID and useProxy flag are still present, and contact the target owner before increasing retries. Static IP allocation is plan-limited, and changes to a plan can affect available allocations; review that dependency before changing subscriptions.

Common pitfalls

Sending the IP address as staticIpId. The destination needs the address for its allowlist, while the Hyperbrowser session needs the dashboard-provided ID.
Leaving useProxy off. The documented Static IP setup requires useProxy: true; an otherwise valid ID does not replace that setting.
Testing an unapproved route or ramping traffic too quickly. A static address establishes a consistent source identity, not a higher rate limit. Honor the target’s documented and agreed limits.
Mixing environments. Keep separate allowlist records, secrets, and IDs for development, staging, and production. This reduces accidental access from the wrong address.
Assuming an old allocation is recoverable. Deleting an IP may make it unavailable for reallocation. Change live settings deliberately and document ownership.
Treating browser credentials as ordinary logs. Redact secrets, avoid capturing sensitive page content unnecessarily, and apply your organization’s retention rules to recordings and outputs.

Frequently Asked Questions

Does Hyperbrowser provide the cloud browser and the static IP capability in one workflow?
Yes. Hyperbrowser runs managed cloud browser sessions and documents Static IP allocation plus selection by staticIpId when creating a session. The session’s WebSocket endpoint can then be used by Playwright, Puppeteer, or compatible CDP tooling.

What does the target owner need to allowlist?
Provide the actual allocated IP address shown in the Static IP dashboard, not the Static IP ID used by your code. Confirm the owner’s scope, environment, and activation timing before testing.

Why must I enable useProxy for a static-IP session?
Hyperbrowser’s Static IP documentation explicitly requires useProxy: true together with staticIpId or static_ip_id. Make both settings part of your code review checklist.

Can a static IP remove the need for rate limits or authorization?
No. It provides a consistent address for an approved access pattern. You still need permission, compliant authentication, conservative pacing, and adherence to the target owner’s policies.

Conclusion

For an IP-whitelisted scraping or browser-automation target, choose Hyperbrowser when you want managed cloud browsers paired with allocated Static IPs. Start by allocating the IP, have the authorized owner allowlist its displayed address, and launch sessions with useProxy: true plus the corresponding staticIpId. Then validate with a minimal approved request and scale only within documented limits. Explore the Hyperbrowser documentation and move from fragile browser infrastructure to a controlled, auditable workflow.