# Session Identity Platform

**Audience:** API integrators and automation builders  
**Status:** Available on WebX (policy env-gated; default is backward-compatible)  
**Portal:** [/docs/session-identity](/docs/session-identity)  
**Related:** [Managed proxies](/docs/managed-proxies) · [Browserbase sessions](/docs/browserbase-migration) · [Full system record](/docs/session-identity-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

```bash
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](/docs/browserbase-migration).

---

## Identity policy

| Policy | Behavior |
|---|---|
| **`permissive`** (default) | Composition succeeds; contradictions do not block admission (backward compatible). |
| **`coherent`** | Fail closed on high-value contradictions (timezone vs country, locale vs country, mobile proxy + desktop UA, requested vs observed country, sticky continuity). |
| **`strict`** | Coherent plus stronger rules (e.g. verified exit country when a geo-check has run; DNS leak signals). |

Deployment knob:

```bash
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`:

```bash
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.

| Env | Purpose |
|---|---|
| `WEBX_PROXY_POOL` / `WEBX_PROXY_POOL_FILE` | Static pool JSON |
| `WEBX_PROXY_INVENTORY_FILE` / `WEBX_PROXY_INVENTORY_URLS` | Refreshable inventory |
| `WEBX_PROXY_GEO_CHECK_URL` | Out-of-band exit country verification |

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

Full detail: [Managed proxies](/docs/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

| Situation | Typical outcome | What to do |
|---|---|---|
| No inventory match for geo | `managed_proxy_unavailable` | Fix pool / country request |
| Timezone/locale vs country clash | Coherence error under coherent/strict | Align fingerprint with geo |
| Sticky context, no managed lease | `identity_continuity` | Request compatible managed proxy or new context |
| Only far failover candidates | `no_safe_failover` | Expand same-country inventory |
| Unverified exit under strict | `proxy_geo_unverified` | Configure geo-check or relax policy |
| Bad fingerprint JSON | Session create fails | Fix `WEBX_FINGERPRINT_PROFILE_JSON` |

---

## 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

| Doc | When to open it |
|---|---|
| [System record](/docs/session-identity-system-record) | Architecture, invariants, ops runbook, ADRs |
| [Managed proxies](/docs/managed-proxies) | Lease API, inventory, receipts |
| [User guide](/docs/user-guide) | Full WebX API surface |
| [Browserbase migration](/docs/browserbase-migration) | `connectOverCDP` / session lifecycle |