Log In and Reuse Sessions

Log in once and reuse that authenticated state across many browser sessions without re-entering credentials.

Prerequisites

• A Browserless API token from your account dashboard

Steps

Authenticated sessions work in two phases: first you save the login state into a named profile, then you reuse that profile across future sessions.

REST API

Use the REST API to manage browser sessions without a persistent connection.

cURL

View Full Code on GitHub

1. Create a profile session

Start a profile-creation session. The response contains a WebSocket URL to connect a CDP client for the login flow:

curl -X POST \
  "https://production-sfo.browserless.io/profile?token=YOUR_API_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-profile" }'

The response includes a connect WebSocket URL and a stop URL:

{
  "id": "<session-id>",
  "name": "my-profile",
  "connect": "wss://production-sfo.browserless.io/session/connect/<id>?token=...",
  "stop": "https://production-sfo.browserless.io/session/<id>?token=..."
}

2. Log in and save the profile

Use a CDP client (Puppeteer or Playwright) to connect to the connect URL, complete the login, and call Browserless.saveProfile. See the Puppeteer tab for a complete code example.

3. Use the saved profile

Once saved, append ?profile=my-profile to any Browserless request to start with the authenticated state pre-loaded:

curl -X POST \
  "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&profile=my-profile" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://app.example.com/dashboard" }' \
  --output dashboard.png

JavaScript

View Full Code on GitHub

1. Create a profile session

const TOKEN = 'YOUR_API_TOKEN_HERE';
const ORIGIN = 'https://production-sfo.browserless.io';

const session = await fetch(`${ORIGIN}/profile?token=${TOKEN}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'my-profile' }),
}).then((r) => r.json());

console.log(session.connect);
// Use session.connect with the Frameworks tab to log in and save.

2. Reuse the saved profile

import fs from 'fs';

const response = await fetch(
  `${ORIGIN}/screenshot?token=${TOKEN}&profile=my-profile`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ url: 'https://app.example.com/dashboard' }),
  }
);

const buffer = await response.arrayBuffer();
await fs.promises.writeFile('dashboard.png', Buffer.from(buffer));
console.log('Screenshot saved.');

Python

View Full Code on GitHub

1. Install dependencies

pip install playwright

2. Log in and save the profile

Profile creation requires a CDP client. Use the Puppeteer or Playwright tab for the save step, then reuse the profile in Python.

3. Reuse the saved profile

from playwright.sync_api import sync_playwright

TOKEN = "YOUR_API_TOKEN_HERE"
WS_ENDPOINT = (
    f"wss://production-sfo.browserless.io/chromium/playwright"
    f"?token={TOKEN}&profile=my-profile"
)

with sync_playwright() as playwright:
    # connect_over_cdp with /chromium/playwright exposes the profile-loaded context.
    browser = playwright.chromium.connect_over_cdp(WS_ENDPOINT)
    try:
        context = browser.contexts[0]
        page = context.pages[0]
        page.goto("https://app.example.com/dashboard")  # already logged in
        print("Title:", page.title())
    finally:
        # Always close to release the session even on error.
        browser.close()

Java

View Full Code on GitHub

1. Add dependencies

<dependency>
  <groupId>com.microsoft.playwright</groupId>
  <artifactId>playwright</artifactId>
  <version>1.44.0</version>
</dependency>

2. Create a profile session

import java.net.http.*;
import java.net.URI;
import java.nio.file.*;

HttpClient client = HttpClient.newHttpClient();

HttpRequest sessionRequest = HttpRequest.newBuilder()
    .uri(URI.create("https://production-sfo.browserless.io/profile?token=YOUR_API_TOKEN_HERE"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"name\": \"my-profile\"}"))
    .build();
HttpResponse<String> sessionResponse = client.send(sessionRequest, HttpResponse.BodyHandlers.ofString());
System.out.println(sessionResponse.body());
// Parse session.connect and use the Playwright Java tab to log in and save.

3. Reuse the saved profile

HttpRequest screenshotRequest = HttpRequest.newBuilder()
    .uri(URI.create("https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&profile=my-profile"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"url\": \"https://app.example.com/dashboard\"}"))
    .build();
HttpResponse<byte[]> screenshotResponse = client.send(screenshotRequest, HttpResponse.BodyHandlers.ofByteArray());
Files.write(Path.of("dashboard.png"), screenshotResponse.body());
System.out.println("Screenshot saved.");

C#

View Full Code on GitHub

1. Create a profile session

using System.Net.Http;
using System.Text;

using var client = new HttpClient();

var sessionBody = new StringContent("{\"name\": \"my-profile\"}", Encoding.UTF8, "application/json");
var sessionResponse = await client.PostAsync(
    "https://production-sfo.browserless.io/profile?token=YOUR_API_TOKEN_HERE",
    sessionBody
);
Console.WriteLine(await sessionResponse.Content.ReadAsStringAsync());
// Parse session.connect and use the Playwright C# tab to log in and save.

2. Reuse the saved profile

var screenshotBody = new StringContent("{\"url\": \"https://app.example.com/dashboard\"}", Encoding.UTF8, "application/json");
var screenshotResponse = await client.PostAsync(
    "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&profile=my-profile",
    screenshotBody
);
var bytes = await screenshotResponse.Content.ReadAsByteArrayAsync();
await File.WriteAllBytesAsync("dashboard.png", bytes);
Console.WriteLine("Screenshot saved.");

Go

View Full Code on GitHub

1. Create a profile session

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    client := &http.Client{}

    sessionBody := bytes.NewBufferString(`{"name": "my-profile"}`)
    sessionReq, _ := http.NewRequest("POST",
        "https://production-sfo.browserless.io/profile?token=YOUR_API_TOKEN_HERE",
        sessionBody,
    )
    sessionReq.Header.Set("Content-Type", "application/json")
    sessionResp, _ := client.Do(sessionReq)
    defer sessionResp.Body.Close()

    var session map[string]string
    json.NewDecoder(sessionResp.Body).Decode(&session)
    fmt.Println(session["connect"])
    // Use session["connect"] with the Frameworks tab to log in and save.

2. Reuse the saved profile

    screenshotBody := bytes.NewBufferString(`{"url": "https://app.example.com/dashboard"}`)
    screenshotReq, _ := http.NewRequest("POST",
        "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&profile=my-profile",
        screenshotBody,
    )
    screenshotReq.Header.Set("Content-Type", "application/json")
    screenshotResp, _ := client.Do(screenshotReq)
    defer screenshotResp.Body.Close()
    data, _ := io.ReadAll(screenshotResp.Body)
    os.WriteFile("dashboard.png", data, 0644)
    fmt.Println("Screenshot saved.")
}

PHP

View Full Code on GitHub

1. Create a profile session

<?php
$ch = curl_init('https://production-sfo.browserless.io/profile?token=YOUR_API_TOKEN_HERE');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => '{"name": "my-profile"}',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);
$session = json_decode(curl_exec($ch), true);
curl_close($ch);
// Use $session['connect'] with the Frameworks tab to log in and save.

2. Reuse the saved profile

$ch2 = curl_init('https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&profile=my-profile');
curl_setopt_array($ch2, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => '{"url": "https://app.example.com/dashboard"}',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);
file_put_contents('dashboard.png', curl_exec($ch2));
curl_close($ch2);
echo "Screenshot saved.\n";

Ruby

View Full Code on GitHub

1. Create a profile session

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://production-sfo.browserless.io/profile?token=YOUR_API_TOKEN_HERE')
response = Net::HTTP.post(uri, '{"name": "my-profile"}', 'Content-Type' => 'application/json')
session = JSON.parse(response.body)
puts session['connect']
# Use session['connect'] with the Frameworks tab to log in and save.

2. Reuse the saved profile

uri2 = URI('https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&profile=my-profile')
response2 = Net::HTTP.post(uri2, '{"url": "https://app.example.com/dashboard"}', 'Content-Type' => 'application/json')
File.binwrite('dashboard.png', response2.body)
puts 'Screenshot saved.'

Frameworks

Use a browser connection to manage sessions directly via Puppeteer or Playwright.

Puppeteer

View Full Code on GitHub

1. Install dependencies

npm install puppeteer-core

2. Log in and save the profile

import puppeteer from 'puppeteer-core';

const TOKEN = 'YOUR_API_TOKEN_HERE';
const ORIGIN = 'https://production-sfo.browserless.io';

const session = await fetch(`${ORIGIN}/profile?token=${TOKEN}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'my-profile' }),
}).then((r) => r.json());

const browser = await puppeteer.connect({ browserWSEndpoint: session.connect });

try {
  const page = await browser.newPage();

  await page.goto('https://app.example.com/login');
  await page.type('#email', 'user@example.com');
  await page.type('#password', process.env.PASSWORD);
  await page.click("button[type='submit']");
  await page.waitForNavigation();

  const cdp = await page.createCDPSession();
  const result = await cdp.send('Browserless.saveProfile', { name: 'my-profile' });
  console.log(result);
  // { ok: true, profileId: '<id>', name: 'my-profile', cookieCount: 12, originCount: 1 }
} finally {
  // Always close to release the session even on error.
  await browser.close();
}

3. Reuse the saved profile

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint:
    'wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&profile=my-profile',
});

try {
  const page = await browser.newPage();
  await page.goto('https://app.example.com/dashboard'); // already logged in
  console.log('Title:', await page.title());
} finally {
  // Always close to release the session even on error.
  await browser.close();
}

Playwright

JavaScript

View Full Code on GitHub

1. Install dependencies

npm install playwright-core

2. Log in and save the profile

import { chromium } from 'playwright-core';

const TOKEN = 'YOUR_API_TOKEN_HERE';
const ORIGIN = 'https://production-sfo.browserless.io';

const session = await fetch(`${ORIGIN}/profile?token=${TOKEN}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'my-profile' }),
}).then((r) => r.json());

const browser = await chromium.connectOverCDP(session.connect);

try {
  const context = browser.contexts()[0];
  const page = await context.newPage();

  await page.goto('https://app.example.com/login');
  await page.fill('#email', 'user@example.com');
  await page.fill('#password', process.env.PASSWORD);
  await page.click("button[type='submit']");
  await page.waitForURL('**/dashboard');

  const cdpSession = await context.newCDPSession(page);
  const result = await cdpSession.send('Browserless.saveProfile', { name: 'my-profile' });
  console.log(result);
  // { ok: true, profileId: '<id>', name: 'my-profile', cookieCount: 12, originCount: 1 }.
} finally {
  // Always close to release the session even on error.
  await browser.close();
}

3. Reuse the saved profile

import { chromium } from 'playwright-core';

const browser = await chromium.connect(
  `wss://production-sfo.browserless.io/chromium/playwright?token=YOUR_API_TOKEN_HERE&profile=my-profile`
);

try {
  // connect() uses Playwright native mode — browser.newPage() creates a page in the
  // profile-loaded default context without needing to access contexts() directly.
  const page = await browser.newPage();
  await page.goto('https://app.example.com/dashboard'); // already logged in.
  console.log('Title:', await page.title());
} finally {
  // Always close to release the session even on error.
  await browser.close();
}

Python

View Full Code on GitHub

1. Install dependencies

pip install requests playwright

2. Log in and save the profile

import requests
from playwright.sync_api import sync_playwright

TOKEN = 'YOUR_API_TOKEN_HERE'
ORIGIN = 'https://production-sfo.browserless.io'

session = requests.post(
    f'{ORIGIN}/profile?token={TOKEN}',
    json={'name': 'my-profile'},
).json()

with sync_playwright() as playwright:
    # connect_over_cdp gives access to CDP sessions needed for Browserless.saveProfile.
    browser = playwright.chromium.connect_over_cdp(session['connect'])
    try:
        context = browser.contexts[0]
        page = context.new_page()

        page.goto('https://app.example.com/login')
        page.fill('#email', 'user@example.com')
        page.fill('#password', 'YOUR_PASSWORD')
        page.click("button[type='submit']")
        page.wait_for_url('**/dashboard')

        cdp = page.context.new_cdp_session(page)
        result = cdp.send('Browserless.saveProfile', {'name': 'my-profile'})
        print(result)
        # {'ok': True, 'profileId': '<id>', 'name': 'my-profile', 'cookieCount': 12, 'originCount': 1}
    finally:
        # Always close to release the session even on error.
        browser.close()

3. Reuse the saved profile

from playwright.sync_api import sync_playwright

WS_REUSE = (
    'wss://production-sfo.browserless.io/chromium/playwright'
    '?token=YOUR_API_TOKEN_HERE&profile=my-profile'
)

with sync_playwright() as playwright:
    browser = playwright.chromium.connect_over_cdp(WS_REUSE)
    try:
        context = browser.contexts[0]
        page = context.pages[0]
        page.goto('https://app.example.com/dashboard')  # already logged in.
        print('Title:', page.title())
    finally:
        # Always close to release the session even on error.
        browser.close()

Java

View Full Code on GitHub

1. Add dependencies

<dependency>
  <groupId>com.microsoft.playwright</groupId>
  <artifactId>playwright</artifactId>
  <version>1.44.0</version>
</dependency>
<!-- Add Gson or Jackson for JSON parsing -->
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.10.1</version>
</dependency>

2. Log in and save the profile

import com.microsoft.playwright.*;
import com.google.gson.*;
import java.net.http.*;
import java.net.URI;

public class SaveSession {
    public static void main(String[] args) throws Exception {
        String token = "YOUR_API_TOKEN_HERE";
        String origin = "https://production-sfo.browserless.io";

        HttpClient http = HttpClient.newHttpClient();
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(origin + "/profile?token=" + token))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("{\"name\": \"my-profile\"}"))
            .build();
        String body = http.send(req, HttpResponse.BodyHandlers.ofString()).body();
        String wsEndpoint = JsonParser.parseString(body)
            .getAsJsonObject().get("connect").getAsString();

        try (Playwright playwright = Playwright.create()) {
            Browser browser = playwright.chromium().connectOverCDP(wsEndpoint);
            try {
                BrowserContext context = browser.contexts().get(0);
                Page page = context.newPage();

                page.navigate("https://app.example.com/login");
                page.fill("#email", "user@example.com");
                page.fill("#password", System.getenv("PASSWORD"));
                page.click("button[type='submit']");
                page.waitForURL("**/dashboard");

                // connectOverCDP gives access to CDP sessions needed for Browserless.saveProfile.
                CDPSession cdp = page.context().newCDPSession(page);
                JsonElement result = cdp.send("Browserless.saveProfile", Map.of("name", "my-profile"));
                System.out.println(result);
                // {"ok":true,"profileId":"<id>","name":"my-profile","cookieCount":12,"originCount":1}
            } finally {
                // Always close to release the session even on error.
                browser.close();
            }
        }
    }
}

3. Reuse the saved profile

String wsReuse = "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&profile=my-profile";

try (Playwright playwright = Playwright.create()) {
    Browser browser = playwright.chromium().connectOverCDP(wsReuse);
    try {
        BrowserContext context = browser.contexts().get(0);
        Page page = context.pages().get(0);
        page.navigate("https://app.example.com/dashboard"); // already logged in.
        System.out.println("Title: " + page.title());
    } finally {
        // Always close to release the session even on error.
        browser.close();
    }
}

C#

View Full Code on GitHub

1. Add dependencies

dotnet add package Microsoft.Playwright

2. Log in and save the profile

using Microsoft.Playwright;
using System.Net.Http;
using System.Text;
using System.Text.Json;

const string Token = "YOUR_API_TOKEN_HERE";
const string Origin = "https://production-sfo.browserless.io";

using var http = new HttpClient();
var sessionBody = new StringContent("{\"name\": \"my-profile\"}", Encoding.UTF8, "application/json");
var sessionResp = await http.PostAsync($"{Origin}/profile?token={Token}", sessionBody);
var sessionJson = JsonDocument.Parse(await sessionResp.Content.ReadAsStringAsync());
var wsEndpoint = sessionJson.RootElement.GetProperty("connect").GetString();

using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.ConnectOverCDPAsync(wsEndpoint);

try
{
    var context = browser.Contexts[0];
    var page = await context.NewPageAsync();

    await page.GotoAsync("https://app.example.com/login");
    await page.FillAsync("#email", "user@example.com");
    await page.FillAsync("#password", Environment.GetEnvironmentVariable("PASSWORD"));
    await page.ClickAsync("button[type='submit']");
    await page.WaitForURLAsync("**/dashboard");

    // ConnectOverCDP gives access to CDP sessions needed for Browserless.saveProfile.
    var cdp = await page.Context.NewCDPSessionAsync(page);
    var result = await cdp.SendAsync(
        "Browserless.saveProfile",
        new Dictionary<string, object> { ["name"] = "my-profile" }
    );
    Console.WriteLine(result);
    // { ok: true, profileId: '<id>', name: 'my-profile', cookieCount: 12, originCount: 1 }
}
finally
{
    // Always close to release the session even on error.
    await browser.CloseAsync();
}

3. Reuse the saved profile

using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.ConnectOverCDPAsync(
    "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&profile=my-profile"
);

try
{
    var context = browser.Contexts[0];
    var page = context.Pages[0];
    await page.GotoAsync("https://app.example.com/dashboard"); // already logged in.
    Console.WriteLine($"Title: {await page.TitleAsync()}");
}
finally
{
    // Always close to release the session even on error.
    await browser.CloseAsync();
}

Next steps

• Scrape Structured Data — extract data from authenticated pages
• Fill and Submit a Form — automate interactions in logged-in flows
• Take a Screenshot — capture authenticated pages as images