Confronta la posizione di un accesso con quella precedente memorizzata

Un grande cambiamento nella posizione derivata dall'IP in un breve intervallo può giustificare una revisione. POST /v1/risk/check confronta la stima attuale della posizione di un utente con il punto precedente memorizzato e restituisce distanza, tempo trascorso, velocità implicita e una classificazione di rischio — contattaci per confermare la disponibilità prima di integrare, poiché l'applicazione indipendente del piano di rischio e la disponibilità del checkout non sono state verificate.

Discuti l'accesso al controllo del rischio Leggi il riferimento del controllo del rischio →

Disponibilità

Questo endpoint condivide lo stesso middleware a chiave segreta della ricerca IP, che verifica solo che una chiave sia una chiave segreta — non applica in modo indipendente una famiglia di piani di rischio separata, e il prezzo di rischio precaricato non ha un prezzo attivo configurato. Verifica con noi i termini e la disponibilità attuali prima di affidarti a questo in produzione.

Input e utilizzo della chiave segreta

Invia un corpo JSON con userId, ip e un booleano opzionale commit (predefinito true) a POST /v1/risk/check con una chiave segreta tramite Authorization: Bearer YOUR_SECRET_KEY — solo da server a server, mai da un browser.

La prima osservazione

Il primissimo controllo di un utente non ha una posizione precedente con cui confrontarsi: restituisce risk: "low", impossibleTravel: false, valori null per distanza/velocità/tempo trascorso e un previousLocation null, e — se commit non è false — memorizza questa osservazione come nuova baseline.

Osservazioni successive

I controlli successivi confrontano la distanza ortodromica tra il punto precedente e quello attuale rispetto al tempo trascorso per ottenere una velocità implicita. Sotto i 500 km/h, il risultato è "low"; tra 500 e 900 km/h, "medium" (un vero volo intercontinentale può atterrare vicino a questo limite); sopra i 900 km/h, "high" e impossibleTravel: true.

Il flag commit

commit è predefinito a true. Impostalo a false per un pre-controllo speculativo — ad esempio, prima di una decisione di autenticazione step-up — che legge la baseline memorizzata senza spostarla, così un controllo legittimo non corrompe la vera cronologia di posizione dell'utente.

Posizioni mancanti

Se ip non può essere risolto in una latitudine/longitudine, l'endpoint restituisce un 422 anziché un'ipotesi a bassa affidabilità.

Conservazione ed eliminazione

La v1 memorizza esattamente una posizione per coppia (il tuo account, userId) — l'osservazione con commit più recente — senza scadenza automatica e senza un endpoint di eliminazione attualmente disponibile; persiste finché il successivo controllo con commit non la sovrascrive. Poiché memorizza una posizione collegata a userId oltre un singolo ciclo di richiesta/risposta, l'uso di questo endpoint rende Watch-IP un responsabile del trattamento di quei dati per tuo conto — consulta l'Addendum sul trattamento dei dati (DPA).

Falsi positivi

La v1 non ha alcuna soppressione consapevole di VPN o datacenter, quindi un rapido cambio di VPN o la normale rotazione IP di una rete mobile possono produrre un risultato elevato. Tratta ogni classificazione come un segnale grezzo per il tuo processo di revisione, non come un verdetto definitivo.

Campi della risposta

risk: low, medium o high, dalle soglie di velocità implicita sopra descritte.
impossibleTravel: Scorciatoia booleana per risk: "high".
distanceKm, impliedSpeedKmh, elapsedSeconds: La distanza e il tempo tra l'osservazione precedente e quella attuale, e la velocità che ne deriva. Null al primissimo controllo di un utente.
previousLocation: country, latitude, longitude e observedAt per la baseline memorizzata prima di questa chiamata. Null al primissimo controllo di un utente.
currentLocation: country, latitude e longitude risolti dall'ip fornito in questa chiamata.

Pre-controllo, poi commit

cURL backend

# Controllo speculativo prima della tua decisione di autenticazione — non sposta la baseline.
curl https://api.watch-ip.com/v1/risk/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_123", "ip": "203.0.113.1", "commit": false}'

# Dopo che la tua verifica di password/2FA ha successo, esegui il commit della nuova baseline.
curl https://api.watch-ip.com/v1/risk/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_123", "ip": "203.0.113.1"}'

commit è predefinito a true, quindi la seconda chiamata sopra aggiorna la baseline memorizzata; la prima, con commit: false, non lo fa.

Domande frequenti

Cosa succede al primo controllo?

Restituisce sempre risk: "low" con un previousLocation null — non c'è ancora nulla con cui confrontare la posizione attuale.

Sopprime i salti VPN?

No. La v1 non ha alcuna soppressione consapevole di VPN o datacenter, quindi cambiare rete o uscita VPN tra un accesso e l'altro può produrre da solo un risultato medio o alto.

Un risultato alto è prova di compromissione?

No. È un calcolo grezzo di distanza nel tempo. Combinalo con le tue prove di autenticazione invece di trattarlo come un verdetto autonomo.

Posso evitare di aggiornare la baseline?

Sì — passa commit: false. Il controllo viene comunque eseguito e restituisce un risultato, ma la posizione memorizzata non viene sostituita.

Per quanto tempo viene conservata la posizione precedente?

Indefinitamente, finché il successivo controllo con commit per quel userId non la sovrascrive — non esiste scadenza automatica né un endpoint di eliminazione nell'implementazione attuale.