Skip to main content

Geo database setup

Geo database setup​

Last verified: 2026-06-16.

Anomalous login detection resolves each sign-in's IP address to a coarse location using a local IP2Location LITE database. The database lives on your own server and is read in-process, so no sign-in ever makes a third-party API call. This page covers getting the free download token, the monthly auto-update, the tier choice, and the required attribution.

Get your free IP2Location download token​

The LITE database is free, but downloading it needs a free account token:

  1. Create a free account at lite.ip2location.com.
  2. Open your account's Download page and copy your download token.
  3. In WordPress, go to Awthy Security → Login activity, paste the token into the geo-database settings, and save.

Awthy can also use Hub-managed database downloads without requiring the store owner to sign in to Hub. In that mode Hub stores the IP2Location token, caches the downloaded archive for reuse across installs, and WordPress still stores and reads the downloaded .BIN locally.

Awthy stores the token encrypted at rest and never shows it again in full or includes it in API responses.

Monthly auto-update​

Once the token is set, Awthy downloads the database into wp-content/uploads/awthy/geo/ and refreshes it monthly on a built-in schedule. The schedule is code-owned: you do not configure the cadence in WordPress, only the token and the tier. A failed monthly download never deletes the working database or blocks sign-ins — Awthy keeps the last good copy and records the error.

You can also trigger an immediate "Update now" from the same settings page.

Update skipped or missing token states​

An immediate update can finish without downloading a file. Awthy should show that result instead of leaving the panel unchanged:

  • Skipped: missing token means no IP2Location download token is configured and Hub-managed downloads are unavailable in the current environment. Add a local token or check the Hub-managed download configuration, then run Update now again.
  • Skipped: already current means the installed database is fresh enough and no download was needed.
  • Failed means the download or file write did not complete. The last working database is kept, and sign-ins are not blocked.

Never send raw login IP addresses to support or Hub to debug a database update. The database download is separate from local sign-in geolocation, and Hub does not receive login IP addresses for lookup.

:::tip Reliable cron on low-traffic sites WordPress cron only runs when your site gets traffic. On a quiet site, set DISABLE_WP_CRON and drive one OS cron entry (for example wp cron event run --due-now, or a request to wp-cron.php) so the monthly refresh fires on time. This is the WordPress equivalent of a single scheduled task entry. :::

DB3 (default) vs DB5 (impossible travel)​

Awthy ships with the smaller, faster tier by default and lets you opt into a larger one:

  • DB3 (default) — country, region, and city. This covers the primary need: detecting a new country, region, or city (for example South Africa, then suddenly the United States). The file is small and the lookup is fast.
  • DB5 (optional) — everything in DB3 plus latitude and longitude, which unlocks impossible-travel detection (true speed-based scoring). DB5 is a larger download; choose it when you want velocity-based detection and can spend the extra disk space.

Switch tiers from Awthy Security → Login activity. Switching to DB5 fetches the larger database on the next update and turns on impossible-travel scoring; switching back to DB3 disables it gracefully.

Privacy and GDPR​

  • Location is approximate, derived from the IP address, and labelled as such throughout the UI.
  • Awthy stores only coarse geography (country / region / city, and coordinates only on DB5). Raw IP coordinates are never written into the audit context.
  • Geo and login-telemetry rows follow a short retention window and are purged automatically; baselines are kept only while the account is active. The lawful basis is the site owner's legitimate interest in account security. See the architecture notes in docs/architecture/database.md for the exact windows.

Required attribution (IP2Location LITE)​

The IP2Location LITE database is licensed CC-BY-SA 4.0, which requires visible attribution wherever it is used. Awthy renders this attribution in-product, and it must also appear here:

This product includes IP2Location LITE data available from https://lite.ip2location.com.

Do not remove this attribution; it is a condition of the database license.

Last updated on