Integration

v2.0.0

Browser Extension

Capture authenticated browser cookies and pass them to AlterLab to scrape behind logins—no password sharing required.

Detecting extension...

Download

Download the extension directly and sideload it into your browser. Store versions are coming soon.

Chrome / Edge / Brave

Manifest V3 · v2.0.0

Firefox

Manifest V2 · v2.0.0

Chrome Web Store

Coming Soon

Firefox Add-ons

Coming Soon

All releases are available on GitHub Releases.

Installation

Until the extension is available on the browser stores, install it manually by sideloading the downloaded zip file.

Chrome / Edge / Brave

1Unzip alterlab-connect-chrome.zip to a folder on your computer (e.g. ~/extensions/alterlab-connect).
2Open chrome://extensions in your browser (or edge://extensions / brave://extensions).
3Enable Developer mode using the toggle in the top-right corner.
4Click Load unpacked and select the unzipped folder.
5Pin the AlterLab Connect icon to your toolbar for easy access.

Auto-updates

Sideloaded extensions do not auto-update. When a new version is released, download the latest zip, replace the folder contents, and click the refresh icon on the extensions page.

Firefox

1Open about:debugging#/runtime/this-firefox in Firefox.
2Click Load Temporary Add-on.
3Select the alterlab-connect-firefox.zip file directly (no need to unzip).
4The extension icon will appear in your toolbar. Click it to get started.

Temporary add-ons

Firefox temporary add-ons are removed when the browser is closed. You will need to re-load the extension after each restart until the add-on is published on Firefox Add-ons.

Overview

Many valuable data sources sit behind authentication walls— internal dashboards, subscription content, account-specific pricing, personalised feeds. The standard scraping approach breaks down here because reproducing a login flow programmatically is fragile and often blocked.

The AlterLab extension solves this with BYOS (Bring Your Own Session). You log into the target site once in your own browser, click a button in the extension, and your live session cookies are securely uploaded to AlterLab. From that point, any scrape request that references your session ID will be executed with those cookies— appearing to the server as your authenticated browser.

No Password Sharing

Credentials never leave your browser. Only cookies are transmitted.

One-Click Capture

Capture all domain cookies in a single click—no dev tools required.

Manifest V3

Built on the latest Chrome extension standard. Each permission is listed and explained below.

How It Works

Getting from a logged-in browser tab to a working session in your scraper takes six steps.

1
Install the extension
Download the extension from the links above and sideload it into your browser following the installation instructions.
2
Navigate to the target site
Open the site you want to scrape and log in as you normally would. Make sure you can see the authenticated content.
3
Click the AlterLab icon
Click the extension icon in the toolbar. The popup shows the current domain and the number of cookies detected.
4
Enter your API key (first time only)
Paste your AlterLab API key into the settings field. The key is stored in your browser’s encrypted local storage and never needs to be entered again.
5
Click "Save to AlterLab"
The extension reads all cookies for the current domain (including parent domains), deduplicates them, and uploads them to AlterLab over HTTPS. You’ll see a confirmation with the generated session ID.
6
Use the session ID in your API calls
Pass the session ID as the session_id parameter in any scrape request. AlterLab injects the cookies automatically on every request in that session.

Features

The extension is designed to be minimal, transparent, and secure by default.

Full domain cookie capture — Reads all cookies matching the current domain and its parent domain (e.g. capturing both app.example.com and example.com cookies for maximum session coverage).
Automatic deduplication — Cookies with the same name, domain, and path are deduplicated before upload so you always get a clean, minimal set.
Cookie values never shown in the UI — The popup displays cookie names and counts for transparency but never renders the raw values, preventing shoulder-surfing leaks.
Custom API URL support — Point the extension at your own self-hosted AlterLab instance by setting a custom base URL in the settings panel.
Dark theme — Matches the AlterLab design system so the popup feels native alongside the dashboard.

Using Sessions in API Calls

After the extension saves your session, you receive a session_id (also visible in the AlterLab dashboard under Sessions). Pass this ID on any scrape request to have AlterLab inject your captured cookies automatically.

Sessions are tied to your API key. Only your account can use a session you created. Cookie values are encrypted at rest and are never returned in API responses.

Python

from alterlab import AlterLab

client = AlterLab(api_key="sk_live_your_key")

# Use a captured browser session to scrape authenticated content
result = client.scrape(
    url="https://example.com/dashboard",
    session_id="your-session-id",
)

print(result.content)

Session expiry

Browser sessions expire when the underlying site cookies expire or when you log out. If you start seeing authentication errors in your scrape results, recapture the session from the extension and update the session ID in your code.

Security

The BYOS model requires careful handling of sensitive data. Here is exactly how the extension and AlterLab protect your session information.

API key storage

Your AlterLab API key is stored in the extension’s local browser storage, which is sandboxed to the extension and not accessible by page scripts.

AES-256-GCM encryption at rest

Cookie values are encrypted with AES-256-GCM before being written to the database. The encryption key is derived per-account and never stored alongside the data.

Cookie values never returned in responses

No AlterLab API endpoint ever returns raw cookie values. The session ID is a reference; the values remain server-side only.

HTTPS-only transmission

Cookies are transmitted exclusively over HTTPS to your configured AlterLab instance. Plaintext upload is rejected.

API key format validation

The extension validates the sk_live_… key format locally before attempting any network request, preventing accidental submissions of incorrect data.

Permissions

The extension requests the permissions below. Several are broad, so each one is explained. webRequest and host access are optional and requested only when you open the Network tab or, one site at a time, when you connect, record or refresh a session. No remote code is loaded or executed.

Permission	Why it's needed
`cookies`	Read cookies for the domain you choose to capture and upload to AlterLab, and read the alterlab.io session cookie for auto sign-in.
`activeTab`	Access the URL and title of the tab you are viewing when you use the extension.
`storage`	Persist your API key, optional custom API URL, per-tab scores (cleared when the browser closes), local session profiles and a random device identifier in local extension storage.
`alarms`	Refresh the toolbar badge and check saved sessions for staleness on a schedule.
`notifications`	Tell you when an agent task is waiting for your approval or an answer, so you can respond from the notification.
`sidePanel`	Show page analysis, captured requests and the Share report action in the browser side panel.
`contextMenus`	Add the right-click actions Scrape this element and Copy selector.
`scripting`	Inject the analysis script into the current tab when you ask for an analysis, and the network-monitor script while the Network tab is open.
`webRequest`	Optional, requested when you open the Network tab. Observe the active tab's network requests locally to list the API endpoints a page calls.
`https:/// and http:/// (host access)`	Optional. The browser asks for one site at a time when you connect, record or refresh a session there, and with webRequest when you open the Network tab, because a page's requests go to many origins. Not granted by default.

Data handling and Limited Use

Page analysis and the network monitor run inside your browser and are not sent to AlterLab. Data is uploaded only when you capture cookies, scrape, or share a report. The use of information received by AlterLab Connect adheres to the Chrome Web Store User Data Policy, including the Limited Use requirements. See section 8A of the Privacy Policy for every data flow.

Up to 5,000 free requests

New accounts receive a one-time $1 starter balance with no credit card required: about 5,000 direct fetch, 500 managed sessions or 250 full browser rendering requests, to explore the platform before committing. Create a free account.

Supabase

Last updated: June 2026