Skip to main content

Quick Start

In one sentence

Serve the collector from your origin, run the edge in front of your app, and read the verdict from your backend — three moving parts, one verdict.

This is the end-to-end happy path. Each step links to its in-depth page; here we keep it to the minimum that produces a verdict. Make sure you have the prerequisites first.

The browser only ever talks to your domain. Your backend talks to Octet server-to-server. The browser never contacts Octet directly — see How It Works for why.

Step 1 — Serve the collector​

Install the collector (from GitHub Packages) and serve octet-collector.js from your own origin, then call verify() on page load. Tag the session with an opaque sessionRef your backend minted for this page view.

<!-- served from YOUR domain, e.g. https://yourapp.com/static/octet-collector.js -->
<script
  src="https://yourapp.com/static/octet-collector.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>
<script>
  octet.verify({
    apiUrl: 'https://yourapp.com/octet',   // your edge, NOT octet
    sessionRef: 'sess_abc123',             // opaque, minted by your backend
  });
</script>

verify() collects and relays the signals; do not use its return value for policy (the browser is untrusted — Step 3 is the source of truth). Full options (ESM import, wsUrl, passiveOnly, abort): Embed the Collector and the Collector API.

Step 2 — Run the edge​

Put the octet-edge binary in front of your app, on the hop that terminates the browser connection (see the one rule). Point your collector's apiUrl at it.

PORT=8080 \
OCTET_URL=https://<your-octet-api-url> \
LICENSE=<your-license-key> \
  ./octet-edge

The edge exposes POST /v1/signals (the collector posts here) and GET /v1/ws (latency channel). Front it with your existing server so apiUrl reaches it — pick your setup:

Step 3 — Read the verdict on your backend​

The authoritative verdict is fetched server-to-server by your backend from Octet's API, keyed by the sessionRef from Step 1 and authenticated with the partner key Octet issues you. Never trust a verdict the browser hands you — read it yourself.

curl -s "https://<your-octet-api-url>/v1/verdict/sess_abc123?waitMs=2000" \
  -H "x-octet-partner-key: <your-partner-key>"
# → { "country": "DE", "confidence": 0.91, "alarm": "none" }

waitMs long-polls (up to 10s) while the browser's collection is still in flight. Then apply your policy — allow, step up to a challenge, or just log. Octet decides nothing. Details: Fetch the Verdict and the Verdict Schema.

What you just built​

browser (your collector)  →  your edge (octet-edge)  →  octet  →  verdict
                                                                    ↓
                                          your backend  ←  GET /v1/verdict/:ref
                                                ↓
                                          your policy

Where to go next​