Authenticated and personalized pages

Overview

The capture worker is a headless browser under our control. It is not a general-purpose proxy: you cannot forward arbitrary Authorization bearer tokens through the API. Instead, combine Basic auth (for simple gates), cookies (for session cookies you already obtained legally), and optional custom headers such as language or AB-test flags.

HTTP Basic authentication

Set auth_user and auth_pass. Playwright applies them to the first navigation challenge. These values are never written to the queued job row when you use background mode—they exist only for the live worker session.

{
  "url": "https://staging.example.com",
  "auth_user": "preview",
  "auth_pass": "secret",
  "output": "png"
}

Cookies

Pass an array of { name, value, domain?, path? } objects via cookies. In GET requests, JSON-encode the array into a single query parameter. This is the right tool when your app issues a session cookie after server-side login and you want to reuse that session for a capture—provided you have permission to automate that account.

{
  "url": "https://app.example.com/home",
  "cookies": [
    {
      "name": "session_id",
      "value": "…",
      "domain": "app.example.com",
      "path": "/"
    }
  ],
  "output": "png"
}

Custom headers

The headers map is validated: keys matching Authorization, Cookie, Host, forwarding headers, or worker secrets are rejected. Typical safe uses include Accept-Language and custom feature flags your site already understands.

curl -X POST "https://screennabster.com/api/v1/capture" \
  -H "X-API-Key: pk_live_…" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"https://example.com\",\"headers\":{\"Accept-Language\":\"nl-NL\"}}" \
  --output localized.png

Async jobs & secrets

When background: true, stored job options omit Basic auth credentials by design. The worker still receives them for the in-flight render, but they are not persisted in Supabase. Plan to resend sensitive fields only through synchronous captures if your compliance policy forbids even ephemeral handling—or keep using cookie-based sessions that are stored in the options JSON (evaluate your own risk posture).

Read the async guide for webhook verification.

Security notes

• Never embed customer passwords in client-side apps—call ScreenNabster only from your backend.
• Rotate preview credentials if a key leaks; revoke API keys from the dashboard immediately.
• Targets must still pass URL safety checks—private network hosts are blocked (see the URL safety guide).