Einen Login-Standort mit dem zuvor gespeicherten Standort vergleichen

Eine große Standortänderung über ein kurzes Zeitintervall hinweg kann eine Prüfung rechtfertigen. POST /v1/risk/check vergleicht die aktuelle Standortschätzung eines Nutzers mit dem zuvor gespeicherten Punkt und liefert Entfernung, verstrichene Zeit, implizierte Geschwindigkeit und eine Risikoeinstufung — kontaktieren Sie uns, um die Verfügbarkeit vor der Integration zu bestätigen, da eigenständige Risiko-Tarif-Durchsetzung und Checkout-Bereitschaft nicht bestätigt sind.

Zugriff auf die Risikoprüfung besprechen Die Risikoprüfungs-Referenz lesen →

Verfügbarkeit

Dieser Endpoint nutzt dieselbe Middleware für geheime Schlüssel wie die IP-Abfrage, die lediglich prüft, dass ein Schlüssel ein geheimer Schlüssel ist — sie erzwingt keine eigenständige Risiko-Tariffamilie, und für die eingerichtete Risiko-Preisgestaltung ist kein aktiver Preis konfiguriert. Bestätigen Sie aktuelle Bedingungen und Verfügbarkeit bei uns, bevor Sie sich in der Produktion darauf verlassen.

Eingabe und Verwendung des geheimen Schlüssels

Senden Sie einen JSON-Body mit userId, ip und einem optionalen commit-Boolean (Standard true) an POST /v1/risk/check mit einem geheimen Schlüssel über Authorization: Bearer YOUR_SECRET_KEY — ausschließlich Server-zu-Server, niemals aus einem Browser.

Die erste Beobachtung

Die allererste Prüfung eines Nutzers hat keinen vorherigen Standort zum Vergleich: Sie liefert risk: "low", impossibleTravel: false, null-Werte für distance/speed/elapsed und ein null-previousLocation, und speichert diese Beobachtung — sofern commit nicht false ist — als neue Baseline.

Spätere Beobachtungen

Spätere Prüfungen vergleichen die Großkreisdistanz zwischen dem vorherigen und dem aktuellen Punkt mit der verstrichenen Zeit, um eine implizierte Geschwindigkeit zu erhalten. Unter 500 km/h ist das Ergebnis „low“; zwischen 500 und 900 km/h „medium“ (ein echter Langstreckenflug kann in der Nähe dieser Grenze landen); über 900 km/h „high“ und impossibleTravel: true.

Das commit-Flag

commit ist standardmäßig true. Setzen Sie es auf false für eine spekulative Vorabprüfung — zum Beispiel vor einer Step-up-Authentifizierungsentscheidung —, die die gespeicherte Baseline liest, ohne sie zu verändern, sodass eine legitime Prüfung die tatsächliche Standorthistorie des Nutzers nicht verfälscht.

Fehlende Standorte

Wenn ip nicht auf einen Breiten-/Längengrad aufgelöst werden kann, liefert der Endpoint einen 422 statt einer Schätzung mit geringer Zuverlässigkeit.

Aufbewahrung und Löschung

v1 speichert genau einen Standort pro Paar (Ihr Konto, userId) — die zuletzt übernommene Beobachtung — ohne automatischen Ablauf und derzeit ohne verfügbaren Löschendpoint; er bleibt bestehen, bis die nächste übernommene Prüfung ihn überschreibt. Da eine mit userId verknüpfte Standortangabe über einen einzelnen Anfrage-/Antwortzyklus hinaus gespeichert wird, macht die Nutzung dieses Endpoints Watch-IP zu einem Auftragsverarbeiter dieser Daten in Ihrem Auftrag — siehe den Auftragsverarbeitungsvertrag (DPA).

Fehlalarme

v1 hat keine VPN- oder rechenzentrumsbewusste Unterdrückung, sodass schnelles VPN-Wechseln oder gewöhnlicher IP-Wechsel bei Mobilfunknetzen ein erhöhtes Ergebnis erzeugen kann. Behandeln Sie jede Einstufung als reines Signal für Ihren eigenen Prüfprozess, nicht als endgültiges Urteil.

Antwortfelder

risk: low, medium oder high, gemäß den obigen Schwellenwerten für die implizierte Geschwindigkeit.
impossibleTravel: Boolesche Kurzform für risk: "high".
distanceKm, impliedSpeedKmh, elapsedSeconds: Die Entfernung und Zeit zwischen der vorherigen und der aktuellen Beobachtung sowie die daraus implizierte Geschwindigkeit. Null bei der allerersten Prüfung eines Nutzers.
previousLocation: country, latitude, longitude und observedAt für die gespeicherte Baseline vor diesem Aufruf. Null bei der allerersten Prüfung eines Nutzers.
currentLocation: country, latitude und longitude, ermittelt aus der bei diesem Aufruf angegebenen ip.

Vorabprüfen, dann übernehmen

Backend-cURL

# Spekulative Prüfung vor Ihrer eigenen Authentifizierungsentscheidung — verändert die Baseline nicht.
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}'

# Nachdem Ihre eigene Passwort-/2FA-Verifizierung erfolgreich war, übernehmen Sie die neue 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 ist standardmäßig true, daher aktualisiert der zweite Aufruf oben die gespeicherte Baseline; der erste, mit commit: false, tut dies nicht.

Häufig gestellte Fragen

Was passiert bei der ersten Prüfung?

Sie liefert immer risk: "low" mit einem null-previousLocation — es gibt noch nichts, womit der aktuelle Standort verglichen werden könnte.

Werden VPN-Wechsel unterdrückt?

Nein. v1 hat keine VPN- oder rechenzentrumsbewusste Unterdrückung, sodass ein Netzwerk- oder VPN-Exit-Wechsel zwischen Logins allein ein mittleres oder hohes Ergebnis erzeugen kann.

Ist ein hohes Ergebnis ein Beweis für eine Kompromittierung?

Nein. Es ist eine reine Distanz-über-Zeit-Berechnung. Kombinieren Sie es mit Ihren eigenen Authentifizierungsbelegen, statt es als eigenständiges Urteil zu behandeln.

Kann ich die Aktualisierung der Baseline vermeiden?

Ja — übergeben Sie commit: false. Die Prüfung läuft weiterhin und liefert ein Ergebnis, aber der gespeicherte Standort wird nicht ersetzt.

Wie lange wird der vorherige Standort aufbewahrt?

Unbegrenzt, bis die nächste übernommene Prüfung für diese userId ihn überschreibt — in der aktuellen Implementierung gibt es keinen automatischen Ablauf und keinen Löschendpoint.