IP Resolvers
To retrieve geolocation data from an IP address, you need to configure an IP resolver. IP Resolvers turn a client IP into geolocation and risk data — country, city, hosting/proxy/Tor status — which feeds Threat Intelligence and other Detection Signals. You can enable more than one; Sentinel merges their results.
Without an IP resolver: timezone fallback
If high accuracy isn't required, you can skip IP resolver configuration entirely. The widget submits the visitor's timezone by default, and Sentinel uses it for low-precision geolocation — inferring a country from the timezone rather than the IP address.
The timezone itself is available via POST /v1/timezone, and as the timeZone field on Classifier requests.
Providers
| Provider | Env var(s) | Notes |
|---|---|---|
| MaxMind | MAXMIND_ACCOUNT_ID, MAXMIND_LICENSE_KEY | Runs locally against a downloaded GeoLite2/GeoIP2 database — no per-request external call. Recommended for compliance-sensitive deployments. |
| HTTP headers | IP_HEADERS_SECRET | Trust x-ip-country-code, x-ip-city, x-ip-region, x-ip-lat, x-ip-lon, x-ip-hosting, x-ip-malicious, x-ip-mobile, x-ip-proxy, x-ip-tor set by something upstream (e.g. your CDN). |
| Cloudflare | CLOUDFLARE_IP_COUNTRY_ENABLED=1 | Country code only, read from Cloudflare's CF-IPCountry header. |
| ip-api.com | IP_API_COM_TOKEN | EU-based, unlimited usage on a paid plan. |
| ipstack.com | IPSTACK_COM_TOKEN | US-based; security indicators require their "Professional Plus" plan or higher. |
| ipinfo.io | IPINFO_IO_TOKEN, optionally IPINFO_IO_LITE_ENABLED or IPINFO_IO_MMDB_DOWNLOAD_URL for local MMDB mode | Token always required; can also run against a locally downloaded database. |
Resolution order
When multiple resolvers are enabled, they run in this order, with later resolvers overriding earlier values only where they actually return data:
- Cloudflare
- HTTP headers
- MaxMind
- ip-api.com
- ipstack.com
- ipinfo.io
Updates and caching
MaxMind and ipinfo.io (in local MMDB mode) refresh their databases on a schedule — MAXMIND_DOWNLOAD_SCHEDULE and IPINFO_IO_MMDB_DOWNLOAD_SCHEDULE, both cron syntax, defaulting to daily at midnight. Resolved results are cached per IP for up to 4 hours.
Verify your configuration
To confirm a resolver is set up correctly:
POST /v1/ip
{ "ip": "1.2.3.4" }The response includes whatever geolocation and risk data your configured resolver(s) return. Some fields may come back null — which fields are populated depends on which resolver you're using and what indicators it supports (e.g. Cloudflare only ever returns a country code; MaxMind's GeoLite2 doesn't include proxy/Tor/hosting detection the way GeoIP2 does).
Recommendation
For compliance-sensitive deployments, prefer a locally hosted MaxMind database over external lookup services, since it doesn't send client IPs to a third party on every request.
Related
- Threat Intelligence and Detection Signals — where resolved data is used.
- Reverse Proxy — getting the correct client IP to Sentinel in the first place.
- ENV Variables — variable reference.