How It Works

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

A collection is one run of the collector: what it gathers in the browser and posts to your edge. Each page view has one sessionRef, and each collection needs its own challenge.

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->>O: POST /v1/challenge { sessionRef } + read token
    O-->>S: { challenge, exp }
    S->>B: page with the sessionRef and challenge
    B->>B: octet.start({ apiUrl, sessionRef, challenge })
    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

Your backend creates a new, unguessable sessionRef for the page view, gets a one-time challenge for it from Octet with your read token, and renders both into the page.
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. In passive mode it does neither.
The collector encrypts what it collected to Octet, and posts it to your edge at /v1/signals.
The edge adds what it sees on the connection itself, including the user's IP address, signs the result with its signing key, and forwards everything to Octet over mutual TLS, with your license token.
Octet refuses a copy of a collection it accepted recently, and a collection without a valid, unused challenge for its sessionRef and your license. It computes the verdict and holds it for 2 minutes, keyed by sessionRef. The edge answers the browser with { "ok": true } and nothing else.
When the user acts, the page awaits octet.ready(), which resolves once step 5 has happened, and then tells your backend.
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:

Your backend creates a sessionRef for the page view and stores it in the user's server-side session.
Your backend requests a challenge for that sessionRef. The challenge is bound to the sessionRef and your license, works for one collection, and expires after 10 minutes.
The page passes the sessionRef and the challenge to octet.start(), and the collector sends both with the collection.
Octet stores the verdict under that sessionRef for 2 minutes.
Your backend fetches the verdict with the sessionRef from the user's session.
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 shows how to generate one and get its challenge.

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 hosts. See Network and CSP.

The edge has to be the machine that accepts the browser's TCP connection and terminates its TLS. It needs the browser's own connection, including the user's IP address. A proxy, load balancer or CDN that terminates TCP or TLS in front of the edge replaces that connection with its own, and verdicts become wrong. See Deploy the Edge.

What stays on Octet's servers

The collector and the edge only collect and forward data. The logic that turns that data into a verdict 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, and Integrity and Audit for how each step of a session is protected.

What Octet keeps

Octet holds each session's full data in memory for 2 minutes so that your backend can fetch the verdict, and then discards it. What it keeps is a device record for each browser on your license. See also Privacy and Data.

Device record

To recognise a returning browser, Understone Ltd, Octet's UK subsidiary, keeps a device record for each browser on your license, under the browser's deviceKey. It adds a session to the record only when the collection was signed by the browser's device key. The record is there so that a browser's past sessions on your license can be used to avoid false alarms in your verdicts.

Device records start for your license from 1 December 2026, once your license has accepted v12.01.2026 of the Octet Browser terms. Until then, GET and DELETE /v1/device/{deviceKey} answer 404 with device_records_not_configured.

For each session, the record holds:

the time of the session
the verdict's country, confidence and alarm
the country of the user's IP address
which of Octet's server-side checks the session passed
a keyed tag of the user's network, which can't be turned back into an address without Octet's secret

For the browser, the record holds:

when the browser was first and last seen
up to 20 hashes each of how the device draws graphics and produces audio, stored in a form keyed separately for each license
the highest processor count it reported
whether a known privacy protection was recognised in the browser

The record holds no IP address, no user agent and no other collected data. It keeps the most recent 200 sessions.

A record is held only for your license. The deviceKey, the network tag and the stored hashes are derived separately for each license, and records are never combined or linked across licenses or partners. Records are used only for your license, and never for marketing, analytics or advertising, or to improve Octet's products or train its models.

You are the controller of the device records, and Understone Ltd is your processor under Annex A (Data Processing) of the Octet Browser terms. It keeps records in the United Kingdom, in Google Cloud's europe-west2 (London) region. Google Cloud is the only sub-processor for device records.

Understone Ltd deletes a record 12 months after the browser was last seen, each session in it 12 months after the session, and each stored hash 12 months after it was last seen. A deletion job runs every day. When your license ends, it deletes all of the license's records within 30 days. When a browser's device key changes, for example after the user clears your site's data, the browser gets a new deviceKey and a new record, and the old record is deleted 12 months after it was last seen.

Get or delete a device record

You handle your users' requests about their device records, for example to see or erase their data. Octet helps through two calls, each with your read token and the browser's deviceKey, and doesn't handle the requests for you. If Octet receives such a request directly, it refers the user to you, where it can tell that you are the controller.

To get one browser's record:

curl "https://geo.octetproof.com/v1/device/$DEVICE_KEY" \
  -H "Authorization: Bearer $OCTET_READ_TOKEN"

To delete it:

curl -X DELETE "https://geo.octetproof.com/v1/device/$DEVICE_KEY" \
  -H "Authorization: Bearer $OCTET_READ_TOKEN"

A read token reaches only its own license's records. A deletion removes the record and every session and hash in it before Octet answers. Octet logs each deletion with the license, the deviceKey, the time and whether a record was deleted, never the record's contents, and keeps the log for 90 days. The responses are in Errors.

Keep the deviceKey with each verdict you store, so that you can find a user's record when they ask. See Device key.