# How It Works

This page follows one session from page load to your policy decision.

## One session, in order

```mermaid
sequenceDiagram
    participant B as Browser (collector)
    participant E as Your edge
    participant O as Octet API
    participant S as Your backend
    S->>B: page with a fresh sessionRef
    B->>B: octet.start({ apiUrl, sessionRef })
    B->>E: WebSocket /v1/ws
    B->>E: POST /v1/signals
    E->>O: POST /v1/signals + license token (mutual TLS)
    O-->>E: accepted
    E-->>B: { "ok": true }
    B->>S: user acts (for example, submits a withdrawal)
    S->>O: GET /v1/verdict/:sessionRef + read token
    O-->>S: { country, confidence, alarm, token }
    S->>S: apply your policy
```

1. Your backend renders the page and creates a new, unguessable `sessionRef` for it.
2. The page calls `octet.start()` as soon as it loads. The collector reads the browser's configuration, measures the network, and opens a WebSocket to your edge.
3. The collector encrypts what it collected to Octet, and posts it to your edge at `/v1/signals`.
4. The edge adds what it sees on the connection itself, including the user's IP address, and forwards everything to Octet over mutual TLS, with your license token.
5. Octet refuses a copy of a collection it accepted recently. It computes the verdict and holds it for 2 minutes, keyed by `sessionRef`. The edge answers the browser with `{ "ok": true }` and nothing else.
6. When the user acts, the page awaits `octet.ready()`, which resolves once step 5 has happened, and then tells your backend.
7. Your backend fetches the verdict from Octet with your read token and applies your policy.

## The session reference

The session reference, `sessionRef`, links each verdict to the page view that produced it. Your backend creates it, and it travels this way:

1. Your backend creates a `sessionRef` for the page view and stores it in the user's server-side session.
2. The page passes it to `octet.start()`, and the collector sends it with the collection.
3. Octet stores the verdict under that `sessionRef` for 2 minutes.
4. Your backend fetches the verdict with the `sessionRef` from the user's session.
5. The signed token carries the same `sessionRef`, so you can check that a token belongs to this session.

Four rules keep `sessionRef` safe:

- **Make it unguessable.** Use at least 128 random bits, encoded URL-safe, because it goes in the fetch URL. Octet keeps the first verdict it receives for a `sessionRef`, so someone who could guess a user's `sessionRef` could send their own collection under it first.
- **Create a new one for each page view.** A second collection under the same `sessionRef` within 2 minutes doesn't replace the first verdict.
- **Fetch with the value from your server-side session.** Don't use a `sessionRef` that the browser sends back to you.
- **Keep it in your records with the verdict.** Octet support needs the `sessionRef` and the time to look into a session.

[Embed the Collector](/docs/browser/integration/embed-collector/#2-create-a-sessionref-on-your-backend) shows how to generate one.

## Why the edge runs on your infrastructure

The collector loads from your own site and sends what it collects only to your edge. No Octet script loads from an Octet domain, and the collector never sends data to the Octet API directly. In `full` and `lite` mode the browser also measures network round trips to three Octet hosts. See [Network and CSP](/docs/browser/reference/network/).

The edge has to be the machine that accepts the browser's TCP connection and terminates its TLS. It reads properties of that connection, including the user's IP address. A proxy, load balancer or CDN that terminates TCP or TLS in front of the edge replaces the browser's connection with its own, and verdicts become wrong. See [Deploy the Edge](/docs/browser/integration/deploy-edge/).

## What stays on Octet's servers

The collector and the edge collect and forward. Neither contains the logic that turns what they collect into a verdict. That logic runs only on Octet's servers, and the verdict is the only result that leaves them.

## Why the browser never gets the verdict

Anything that reaches the browser can be read and changed by the user. So the edge returns only `{ "ok": true }` to the browser, and your backend fetches the verdict from Octet directly. Each verdict also carries a signed token, which lets you check later that a stored verdict came from Octet unchanged. See [Verify the Signed Token](/docs/browser/integration/verify-token/), and [Integrity and Audit](/docs/browser/concepts/integrity/) for how each step of a session is protected.

## What Octet keeps

Octet keeps no per-user record. It holds each session's data in memory for 2 minutes so that your backend can fetch the verdict, and then discards it. See [Privacy and Data](/docs/browser/concepts/privacy/).