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.

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