Verdict Reference

This is the body of a 200 response from GET /v1/verdict/{sessionRef}. Verdicts explains how to read them.

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

Fields

Field	Type	Always present	Description
`country`	string	No	ISO 3166-1 alpha-2 code, uppercase. Territories have their own codes, such as `PR` and `GU`. Absent when Octet could not determine a country.
`confidence`	number	Yes	From `0` to `1`. How certain Octet is of `country`.
`alarm`	string	Yes	One of `none`, `low`, `medium`, `high`.
`deviceKey`	string	No	A key for the user's browser, scoped to your license. See Device key.
`token`	string	Yes	The signed copy of the verdict, with its `sessionRef` and the time it was issued. See Verify the Signed Token.

Ignore fields you don't recognise, so that fields added in a later version don't break your code.

Device key

deviceKey lets you recognise a returning browser. It has the form <prefix>_<value>: a short lowercase prefix, an underscore, and 43 base64url characters, for example dk1_….

The same browser gets the same deviceKey on your license, and a different one on every other license, so it can't link users across Octet customers.
It changes when the browser's own key changes, for example after the user clears your site's data, in a private window, or after Safari's 7-day limit on script-written storage.
It changes for every browser at once if Octet replaces the secret it is derived from. The prefix changes too, so you can tell.
Understone Ltd, Octet's UK subsidiary, keeps a device record for each deviceKey on your license, as your processor and only for your license. To get one, send GET /v1/device/{deviceKey} with your read token. To delete one, send DELETE /v1/device/{deviceKey}. See Device record.

The signed token carries the same value from token version 2. See Verify the Signed Token.

Alarm levels

Level	Meaning
`none`	Nothing contradicts `country`.
`low`	A minor inconsistency, for example a traveller. Use `country` as returned.
`medium`	The connection appears masked, for example by a VPN or proxy. Don't trust `country`.
`high`	The connection is masked, or Octet determines the device is being used in a country under comprehensive sanctions, masked or not. `country` is still the country the user is in. Octet does not reliably detect sanctioned regions inside a country, such as Crimea. See Sanctioned regions.

Token claims

The token's claims are listed in Verify the Signed Token.