# 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](/docs/sentinel/features/threat-intelligence/) and other [Detection Signals](/docs/sentinel/features/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](/docs/integration/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.

<Callout>

Timezone-based location is noticeably lower precision than an IP resolver — it can only narrow down a rough region (often spanning several countries) and can't provide city-level accuracy, hosting/proxy/Tor detection, or the other risk indicators a real resolver gives you. Configure a resolver below if geolocation accuracy actually matters for your Security Group rules.

The timezone itself is available via `POST /v1/timezone`, and as the `timeZone` field on [Classifier](/docs/sentinel/features/classifier/#using-the-api) 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. |

> **Warning:**
>
> If you use the HTTP headers resolver, make sure your load balancer or proxy strips any client-sent `x-ip-*` headers before they reach Sentinel — otherwise a client could spoof its own geolocation/risk data.

## Resolution order

When multiple resolvers are enabled, they run in this order, with later resolvers overriding earlier values only where they actually return data:

1. Cloudflare
2. HTTP headers
3. MaxMind
4. ip-api.com
5. ipstack.com
6. 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](/docs/sentinel/features/threat-intelligence/)** and **[Detection Signals](/docs/sentinel/features/detection-signals/)** — where resolved data is used.
- **[Reverse Proxy](/docs/sentinel/operations/reverse-proxy/)** — getting the correct client IP to Sentinel in the first place.
- **[ENV Variables](/docs/sentinel/operations/env-variables/#geolocation--risk-detection)** — variable reference.