Skip to main content

Geolocation Verification

The Geolocation Verification step allows organizations to verify the physical location of a user during the verification flow. This process cross-references the device's reported coordinates with network-level data to ensure the user is present in an authorized region and is not attempting to mask their location.

How It Works​

The verification process follows a two-step sequence to ensure the integrity of the location data:

  1. Initialization: The client requests a geolocation verification start. The system generates and returns a unique, time-limited nonce.
  2. Proof Submission: The client submits the geolocation proof, which includes GPS coordinates, device fingerprint, the provided nonce, permission status, and network metadata such as RTC candidates.
  3. Validation: The system performs reverse geocoding on the coordinates to determine the country. This is then compared against the IP-based country data derived from request headers or Cloudflare trace data.
  4. Result: If the coordinates and IP country do not match, the verification fails with a "location_ip_mismatch" reason.

Customize Settings​

General Details​

  • Name: The name of the flow step used for internal identification.
  • VPN Detection: When enabled, the system checks if the user is connecting through a known VPN or proxy service.
  • IP Validation: Enables strict validation of the user's IP address against known blacklists and reputation databases.
  • Location Cross-Check: Performs a mandatory comparison between the device's GPS coordinates and the network's reported location.
  • Success Button Label: The text displayed on the button after a successful location verification.

Technical Details​

  • Rate Limiting: The initialization endpoint is limited to 10 requests per 60 seconds. The verification submission endpoint is limited to 10 requests per 120 seconds.
  • Nonce Expiry: The verification nonce is valid for 300 seconds (5 minutes). Proofs must be submitted within this window.
  • Result Fields: The verification result includes the status, failure reason (if applicable), detected country, IP address, device fingerprint, VPN status, and whether the IP is blacklisted.