IP Resolvers

To retrieve geolocation data from an IP address, you must configure an IP resolver. ALTCHA Sentinel supports several options. For compliance purposes, we recommend using a locally hosted MaxMind database.

Note

While configuring an IP resolver is recommended for precise geolocation, Sentinel also provides low-precision geolocation based on the user’s timezone.

• If high accuracy isn’t required, you can skip IP resolver configuration.
• The Widget automatically submits the user’s timezone by default.

For details, see: Timezone Resolver API Docs.

Supported Providers

• MaxMind
• HTTP Headers
• ip-api.com
• ipstack.com

MaxMind

ALTCHA Sentinel supports MaxMind GeoIP2 and GeoLite2 binary databases, enabling privacy-friendly IP lookups directly within Sentinel without external services.

MaxMind offers free city-level databases (GeoLite2) - you only need to register and configure your Account ID and License Key.

Configure MaxMind using the following environment variables:

• MAXMIND_ACCOUNT_ID: Your MaxMind Account ID
• MAXMIND_LICENSE_KEY: Your MaxMind License Key
• MAXMIND_DOWNLOAD_URL: Download URL for the binary database (in .tar.gz format; defaults to https://download.maxmind.com/geoip/databases/GeoLite2-City/download?suffix=tar.gz)

For paid GeoIP2 databases, configure the download URL to point to the correct file (e.g., GeoIP2-City).

For more information, visit maxmind.com.

HTTP Headers

If your load balancer or internet gateway supports geolocation, you can pass the following HTTP headers with requests:

x-ip-secret: XXXXXX                 # Authentication secret (required)
x-ip-country-code: US               # ISO 3166-1 alpha-2 country code
x-ip-city: Washington               # City name
x-ip-region: District of Columbia   # Region/state name
x-ip-lat: 38.9034                   # Latitude (decimal degrees)
x-ip-lon: -76.9882                  # Longitude (decimal degrees)
x-ip-hosting: ?1                    # Is IP associated with a datacenter/hosting?
x-ip-malicious: ?0                  # Is IP blacklisted or a known malicious actor?
x-ip-mobile: ?0                     # Is IP a mobile network?
x-ip-proxy: ?0                      # Is IP a known proxy provider?
x-ip-tor: ?0                        # Is IP a known TOR exit node?

Authentication

To authenticate the headers, you must:

1. Configure the IP_HEADERS_SECRET environment variable.
2. Include the x-ip-secret header with the same value.

This ensures that Sentinel verifies the headers were set by your load balancer and not modified by the client.

Security Best Practices

Your load balancer should:

• Strip any client-sent x-ip-* headers.
• Or override all supported headers (use empty values if data is unavailable).

Boolean Values

Accepted formats for boolean fields (x-ip-hosting, x-ip-malicious, etc.):

• True: ?1, 1, true
• False: ?0, 0, false

ip-api.com

The ip-api.com service provides precise geolocation data and advanced detection for hosting or proxy IP addresses with unlimited usage. The service has servers worldwide and is operated by an EU-based company.

Configure ip-api.com using the following environment variable:

• IP_API_TOKEN: Your API token for ip-api.com

For more information, visit ip-api.com.

ipstack.com

ipstack.com offers a global IP database service with advanced security indicators. This service is operated by a US-based company.

To set up ipstack.com, use the following environment variable:

• IPSTACK_COM_TOKEN: Your API token for ipstack.com.

For security indicators (e.g., proxy detection, hosting, TOR), ensure you subscribe to the “PROFESSIONAL PLUS” plan which includes the “Security Module”.

For more details, visit ipstack.com.

Verify Configuration

To confirm that your IP resolver is configured correctly, use the following endpoint:

POST /v1/ip (API Docs)

Submit your IP address in the request. If configured properly, the response will include your IP’s geolocation data.

Note: Some fields in the response may be null, depending on the chosen resolver and the supported indicators.