Use location changes to inform login review

Compare a login's IP-derived location with the previous stored point for that user to flag logins worth a second look.

View pricing Read the risk-check reference →

Availability

POST /v1/risk/check uses the same secret key as IP lookup — there's no separate risk plan, signup, or price. Every check counts as one request against your existing plan's monthly cap.

Reliable client-IP extraction

Watch-IP does not extract the end user's IP from your request for this endpoint — you supply it as ip. Resolve it from your own trusted proxy/CDN header chain on your backend, the same care you'd apply anywhere you trust a client IP for a security decision.

Opaque user ID

Pass your own internal identifier as userId. Watch-IP keeps exactly one stored location per (your customer account, userId) pair — reuse the same identifier across a user's logins so the baseline stays meaningful.

First baseline, then a pre-check

A user's first-ever call always returns risk: "low" with a null previousLocation — there's nothing to compare against yet. For later logins, call with commit: false as an early signal ahead of your own authentication decision; that call reads the stored baseline without moving it.

Commit after your own verification

Once you're confident the login is legitimate — password and any second factor already verified — call again with commit left at its default (true) so this observation becomes the new baseline for the next login.

Concurrency and retries

v1 stores a single most-recent point, not a history — two committed calls close together overwrite the same value, and a retried request after a timeout can itself commit and shift the baseline. Design your retry logic with that in mind rather than assuming each commit is independently recorded.

Legitimate network changes

Business travel, hotel or airport wifi, mobile-carrier IP churn, and ordinary VPN use can all produce a medium or high classification — v1 has no VPN/datacenter-aware suppression. Treat a flagged login as one input to your own review process, not proof of compromise.

What this doesn't guarantee

A high classification is a raw speed calculation between two points, not confirmation of account takeover, and a low classification doesn't clear a login that's suspicious for other reasons. Retention follows the storage behavior above: the stored point persists until the next committed check overwrites it, with no automatic expiry and no deletion endpoint currently available — factor that into any data-retention commitments you make to your own users.