Session Identity Platform

Audience: API integrators and automation builders
Status: Available on WebX (policy env-gated; default is backward-compatible)
Portal: /docs/session-identity
Related: Managed proxies · Browserbase sessions · Full system record

What this is

WebX can bind a browser fingerprint, proxy egress, geography, DNS mode, and sticky context into one authoritative session identity so a run looks and routes like a single consistent browser — not a random mix of signals.

That matters when you:

• Automate logged-in third-party portals
• Need geo-pinned egress with evidence of where traffic actually exited
• Reuse a persistent context (cookies) without silently changing network identity
• Must fail closed when identity cannot be kept coherent

WebX is not an “undetectable browser” product. Identity is about coherence, stickiness, and honest evidence.

Quick start

1. Create a geo-pinned browser session

curl -s -X POST "$WEBX_BASE/v1/sessions" \
  -H "X-BB-API-Key: $WEBX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout": 300,
    "proxies": [{
      "type": "webx",
      "geolocation": { "country": "US" },
      "rotation": "per_session",
      "stickyKey": "login-flow-7"
    }]
  }' | jq

When a managed lease is active, the session response includes a proxy receipt (provider, requested geo, optional observed exit country, lease hash, bytes). Credentials never appear in the receipt.

2. Reuse a sticky login context

Create or supply a contextId so Chromium cookies and a secret-free network snapshot (webx-network-identity.json) stay together. On the next session, WebX prefers the prior lease family instead of inventing a contradictory egress.

Persistent contexts are supported only by an engine that can enforce an exclusive writable profile lease (the process tier). The profile carries an immutable project/profile identity, browser-format version, storage generation, and monotonically increasing owner epoch in webx-profile.json. WebX acquires that fence before removing Chrome singleton files or launching a browser, advances the generation only after a clean browser exit, and rejects concurrent, cross-project, stale-generation, and incompatible-format opens. Shared-browser or lightweight engines return an explicit capability error; a contextId is never accepted while persistence is silently ignored.

Set WEBX_BROWSER_PROFILE_FORMAT_VERSION to a deployment-specific value (for example chromium-151-profile-v1) and change it when rolling to an unqualified Chrome/profile format. Existing profiles then fail with persistent_profile_format_incompatible until a controlled migration is completed; WebX never silently upgrades the writable directory.

If a node dies while owning a profile, its durable lease remains. WebX does not guess that the browser is gone and does not steal the directory after a timer. An operator must first prove the old workload and browser process are absent, then perform the deployment's audited recovery procedure. This temporarily reduces availability but avoids concurrent mutation of authenticated cookies and local storage.

Under coherent / strict identity policy, reusing a context that previously had a concrete managed network requires a compatible managed proxy — silent “cookies only, direct egress” is rejected.

3. Connect with Playwright

Use the session connectUrl from the create response (Browserbase-compatible data plane). See Browserbase migration.

Identity policy

Deployment knob:

WEBX_IDENTITY_POLICY=permissive   # default
# WEBX_IDENTITY_POLICY=coherent
# WEBX_IDENTITY_POLICY=strict

Unknown non-empty values fail closed on the admission path (no silent downgrade to permissive).

Fingerprint profile

Operators can pin an immutable fingerprint with schema webx.fingerprint.v1:

WEBX_FINGERPRINT_PROFILE_JSON='{"schema_version":"webx.fingerprint.v1", ...}'

Invalid or internally contradictory profiles prevent browser session creation. When the live Chrome product string is known, major version must match the profile under fail-closed policy.

Managed proxies

Managed proxies are opt-in via operator inventory. Requesting a managed geo with no healthy matching entry returns 400 managed_proxy_unavailable — WebX does not silently pick another country.

If geo-check is unset or fails, observedCountry stays null (never fabricated).

Full detail: Managed proxies.

Failover and continuity

• Sticky reacquire prefers preferred_lease_hash when the endpoint is healthy.
• Identity-preserving failover chooses the minimum identity distance healthy route.
• Country changes are never silent under identity-preserving mode (distance barrier).
• If no safe route exists → honest no_safe_failover style failure.

What you get as evidence

Secret-free identity digests and proxy receipts can appear on run manifests / session metadata:

• Identity id + content digest
• Fingerprint profile digest
• Proxy lease digest / class / provider
• Requested vs observed country
• Identity policy + version

Never logged or returned: proxy passwords, credential-bearing proxy URLs.

Error guide

Non-goals (read carefully)

• Not probabilistic fingerprint simulation / JA3 spoofing
• Not a guarantee of bypassing bot-management products
• Not multi-worker portable context v2 (object-store CAS) unless your deployment provides shared profile storage

Acceptance coverage

Platform behavior for identity/network is gated by UAT-047 … UAT-054 (composition, geo fail-closed, sticky context, failover distance, DNS, drift, quarantine, cross-context isolation).

Deeper reading