How It Works

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

One session, in order

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
    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 posts what it collected 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 with your license token.
5. Octet 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, is how a verdict finds its way back to the right user. 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 this 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 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 contacts three Octet network hosts. See Network and CSP.

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.

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.

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.