Fetch the Verdict

Your backend fetches each session's verdict directly from Octet with a read token. See Credentials for how to create one.

The request

curl -s "https://geo.octetproof.com/v1/verdict/$SESSION_REF?waitMs=5000" \
  -H "Authorization: Bearer $OCTET_READ_TOKEN"

The responses

200: the verdict.

{
  "country": "DE",
  "confidence": 0.91,
  "alarm": "none",
  "deviceKey": "dk1_bvlgyviLtYS6pbE9nt7wA11rwpiH73CPbsBOhOQOEWg",
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6Im9jdGV0LWJyb3dzZXItdmVyZGljdCtqd3Q7dj0zIi..."
}

Every field is described in Verdict Reference. token is the signed copy of the verdict. See Verify the Signed Token.

404: no verdict for this sessionRef.

{ "status": "pending", "ref": "Vq3n0m6c2x6J5aZ8yP1tQw" }

Octet answers 404 in any of these cases:

• The session hasn't reached Octet yet. Retry with a waitMs.
• The verdict is more than 2 minutes old and has been discarded.
• The sessionRef is wrong, or the collector never ran.
• The session arrived under a different license from your read token's license.

401: the read token was refused. The body names the reason, for example { "error": "expired" }. See Errors.

503: { "error": "verdict_signing_unavailable" }. Octet could not sign the verdict. Retry after a short wait.

How long a verdict lasts

Octet holds each verdict for 2 minutes after the session reaches it. Within that time you can fetch it as often as you like. Repeated fetches can return the same token, which stays valid until its exp. After 2 minutes the fetch returns 404.

Octet stores the first verdict for a sessionRef and keeps it until it expires. A second collection with the same sessionRef within those 2 minutes doesn't replace it. Use a new sessionRef for each page view. See The session reference.

Node.js

Node.js 18 or later, with no dependencies:

const OCTET = 'https://geo.octetproof.com';

export async function fetchVerdict(sessionRef) {
  const url = `${OCTET}/v1/verdict/${encodeURIComponent(sessionRef)}?waitMs=5000`;
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.OCTET_READ_TOKEN}` },
    signal: AbortSignal.timeout(8000),
  });
  if (res.status === 404) return null; // no verdict: treat as unknown
  if (!res.ok) throw new Error(`octet verdict fetch failed: ${res.status} ${await res.text()}`);
  return res.json();
}

Python

Python 3.9 or later, with requests:

import os
import urllib.parse

import requests

OCTET = "https://geo.octetproof.com"


def fetch_verdict(session_ref: str):
    url = f"{OCTET}/v1/verdict/{urllib.parse.quote(session_ref, safe='')}"
    res = requests.get(
        url,
        params={"waitMs": 5000},
        headers={"Authorization": f"Bearer {os.environ['OCTET_READ_TOKEN']}"},
        timeout=8,
    )
    if res.status_code == 404:
        return None  # no verdict: treat as unknown
    res.raise_for_status()
    return res.json()

Set your HTTP client's timeout longer than waitMs, as both examples do.

Apply your policy

Decide what a missing verdict means before you go live. For a regulated action, treat it like a masked connection. See Verdicts for a policy example.