Rules Catalog

Smart Auth evaluates user context during each authentication attempt to determine whether the access is legitimate. These evaluations are grouped by context type — Device, Location, and Network — and each one may contain specific rules that can approve, challenge, or block the attempt.

This page documents the available rules, how they work, and what to expect in the API response when they are triggered.

---

Location Context Rules

The location context evaluates whether the user's geographical information is consistent and trustworthy. It relies on data such as GPS coordinates, IP-based geolocation, and device-reported timezone.

Timezone Mismatch

The Timezone Mismatch rule detects inconsistencies between the timezone reported by the user's device and the geographical information inferred from their network (IP address).

Why it matters

When a user's device reports a timezone that does not match the country or region detected by their IP address, it may indicate the use of a VPN or location spoofing to mask the real origin of the request — a common pattern in fraud attempts.

How it works

When the Location context is enabled and the timezone mismatch rule is active in the access policy, Smart Auth performs a two-layer validation on each authentication attempt:

Layer 1 — Country Allowlist

Smart Auth maintains an allowlist of valid timezones for each country, based on the IANA Time Zone Database. It compares the timezone reported by the user's device against the list of timezones associated with the country detected from the IP address.

For example, if the IP indicates the user is in Brazil (BR), the device timezone must be one of the Brazilian timezones (e.g., America/Sao_Paulo, America/Manaus, America/Bahia, etc.).

If the device timezone does not belong to the detected country's timezone list, the attempt is blocked.

Layer 2 — VPN Fingerprint Confidence

If the first validation passes, Smart Auth performs a second check based on VPN fingerprint data. It evaluates whether detection signals — such as VPN metadata and timezone comparison heuristics — suggest a mismatch. If the confidence score meets or exceeds the configured threshold, the attempt is blocked.

Both layers must be evaluated in sequence. An attempt is only considered valid for the timezone rule if it passes both validations.

Policy configuration

The timezone mismatch rule is configured within the Location context of your access policy. It supports three modes:

Mode	Behavior
Allow	Timezone mismatch detection is disabled. No validation is performed.
Block	If a timezone mismatch is detected, the authentication attempt is immediately denied.
Challenge	If a timezone mismatch is detected, the user is challenged to provide GPS-based location verification. If the SDK does not support GPS challenge, the mismatch is bypassed.

The Challenge mode requires SDK support for GPS-based location challenge. If the user's SDK version does not support this feature, the timezone mismatch will be bypassed instead of blocking the attempt.

API response

When a timezone mismatch is detected and the attempt is blocked, the GET /authentications/{attemptId} response will contain the following information in the contextEvaluation object:

{
  "contextEvaluation": {
    "location_context": {
      "status": "blocked",
      "reason": "TIMEZONE_MISMATCH",
      "description": "TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST"
    }
  }
}

When this rule triggers a block, the reason field is TIMEZONE_MISMATCH and the description field indicates the specific cause:

Description	Meaning
TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST	The device timezone is not a valid timezone for the country detected by the network.
TIMEZONE_CONFIDENCE_THRESHOLD_EXCEEDED	VPN fingerprint analysis detected a timezone mismatch with high confidence.

Additionally, the response includes the raw timezone data collected during the attempt:

Field	Location in response	Description
timezoneFromDevice	context.device.info	The timezone reported by the user's device (e.g., America/Sao_Paulo).
timezoneFromIp	context.network	The timezone inferred from the user's IP address (e.g., Europe/London).

These fields are always returned in the authentication response when available, regardless of whether the timezone mismatch rule is active.

Example scenario

Consider a user whose identity is registered in Brazil:

1. The user initiates an authentication attempt.
2. Smart Auth detects the device timezone as Europe/London.
3. The IP address resolves to a Brazilian provider, indicating country BR.
4. Europe/London is not in the list of valid timezones for BR.
5. The attempt is blocked with reason TIMEZONE_MISMATCH and description TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST.

This could indicate the user is using a Brazilian VPN but is physically located in Europe — or that the device timezone was manually changed.