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. Minimal permissions footprint.

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 using your browser’s encrypted storage API, which is sandboxed to the extension and never 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 minimum set of browser permissions needed to function. No broad host access, no background page, no remote code execution.

Permission	Why it's needed
`cookies`	Read cookies for the active domain so they can be captured and uploaded to AlterLab.
`activeTab`	Access the URL of the current tab to determine which domain's cookies to capture. Access is granted only while the popup is open.
`storage`	Persist your API key and optional custom API URL in the browser's local encrypted storage so they survive browser restarts.

No broad host permissions

Unlike many extensions, AlterLab Connect does not request <all_urls> or any wildcard host access. It only reads cookies from the tab you are actively viewing when the popup is open.

Supabase

Last updated: June 2026