Skip to main content
POST
VPN Detection
Checks the applicant’s IP address against the anonymizer feed — Tor exit nodes, Apple iCloud Private Relay egress ranges, datacenter ranges, and VPN ranges — using the session’s vpn-detection step configuration. Persists its result to the session. Each match type carries a fixed confidence — Tor 95, Private Relay 80, datacenter 90, VPN 85 — and is checked in that order (Tor, Private Relay, datacenter, VPN); the first enabled match wins and is compared against confidence_threshold (default 70). A threshold above a type’s confidence effectively disables that type. trusted_ip_list (CIDRs) and trusted_asn_list short-circuit to CLEAR.
iCloud Private Relay egress addresses are published by Apple and matched as their own type, RELAY, before the datacenter and VPN ranges they overlap. Apple keeps a relay user in their real country and region, so on new workflows a relay hit defaults to flag (relay_action) rather than block. Workflows saved before Private Relay detection existed keep it off, so relay addresses are evaluated exactly as before (as datacenter/VPN) until you turn relay_enabled on. Apple guarantees only country and time zone, so for US state-level geofencing consider relay_action: "block". Set relay_action to change that, or relay_enabled: false to treat relay addresses like any other datacenter/VPN address.
This check fails soft. If an internal error occurs or the anonymizer feed can’t be loaded, it returns 200 with verdict: "UNAVAILABLE" and action: "allow" rather than blocking or erroring. A value that isn’t a valid IPv4 or IPv6 address returns 400.

Request

Headers

Body parameters

Bodies use snake_case field names — there are no camelCase aliases.

Example request

Response

200 — Success

Verdicts

Evidence

Step not configured

If the session’s workflow doesn’t include the VPN_DETECTION step, or the session has no workflow, the check returns 409 and nothing is evaluated or stored. Add the step to the workflow first.

Error responses