Watch-IP

로그인 위치를 이전 저장 위치와 비교하기

짧은 시간 안에 IP 기반 위치가 크게 변하면 심사가 필요할 수 있습니다. POST /v1/risk/check는 사용자의 현재 위치 추정값을 이전 저장 위치와 비교해 거리, 경과 시간, 추정 속도, 위험 분류를 반환합니다 — 독립적인 위험 요금제 시행 여부와 체크아웃 준비 상태가 아직 확인되지 않았으므로 통합 전에 이용 가능 여부를 문의하세요.

위험 확인 접근 권한 문의하기위험 확인 레퍼런스 읽기 →

이용 가능 여부

이 엔드포인트는 키가 시크릿 키인지 확인하는, IP 조회와 동일한 시크릿 키 미들웨어를 공유합니다 — 별도의 위험 요금제 그룹을 독립적으로 시행하지 않으며, 시드로 등록된 위험 가격에는 활성화된 가격이 설정되어 있지 않습니다. 프로덕션에서 이 기능에 의존하기 전에 현재 조건과 이용 가능 여부를 저희에게 확인하세요.

입력값과 시크릿 키 사용

userId, ip, 선택적인 commit 불리언(기본값 true)을 담은 JSON 본문을 Authorization: Bearer YOUR_SECRET_KEY로 시크릿 키를 사용해 POST /v1/risk/check로 전송하세요 — 서버 간 통신 전용이며 브라우저에서는 절대 호출하지 마세요.

첫 번째 관측

사용자의 첫 확인에는 비교할 이전 위치가 없습니다: risk: "low", impossibleTravel: false, null인 distance/speed/elapsed 값, null인 previousLocation을 반환하며 — commit이 false가 아니라면 — 이 관측값을 새로운 기준 위치로 저장합니다.

이후 관측

이후 확인에서는 이전 지점과 현재 지점 사이의 대권 거리(great-circle distance)를 경과 시간과 비교해 추정 속도를 계산합니다. 500km/h 미만이면 "low", 500~900km/h이면 "medium"(실제 장거리 비행이 이 경계 근처에 착륙할 수 있습니다), 900km/h 초과이면 "high"이며 impossibleTravel: true입니다.

commit 플래그

commit의 기본값은 true입니다. 예를 들어 추가 인증 결정에 앞서 사변적인 사전 확인을 위해 false로 설정하면, 기준 위치를 이동시키지 않고 저장된 값을 읽기만 합니다. 이렇게 하면 정당한 확인이 사용자의 실제 위치 히스토리를 손상시키지 않습니다.

위치를 확인할 수 없는 경우

ip를 위도/경도로 해석할 수 없으면 이 엔드포인트는 신뢰도 낮은 추측 대신 422를 반환합니다.

보관 및 삭제

v1은 (계정, userId) 쌍마다 정확히 하나의 위치 — 가장 최근에 커밋된 관측값 — 만 저장하며, 자동 만료나 현재 이용 가능한 삭제 엔드포인트가 없습니다. 다음 커밋된 확인이 덮어쓸 때까지 유지됩니다. 단일 요청/응답 주기를 넘어 userId와 연결된 위치를 저장하기 때문에, 이 엔드포인트를 사용하면 Watch-IP는 귀하를 대신해 해당 데이터를 처리하는 처리자가 됩니다 — 데이터 처리 계약(DPA)을 참고하세요.

오탐

v1에는 VPN이나 데이터센터를 고려한 억제 기능이 없으므로, 빠른 VPN 전환이나 일반적인 모바일 네트워크의 IP 변경이 상승된 결과를 유발할 수 있습니다. 모든 분류를 최종 판정이 아니라 자체 심사 프로세스를 위한 원시 신호로 취급하세요.

응답 필드

risk
위의 추정 속도 임계값에 따른 low, medium, high입니다.
impossibleTravel
risk: "high"를 나타내는 불리언 축약형입니다.
distanceKm, impliedSpeedKmh, elapsedSeconds
이전 관측과 현재 관측 사이의 거리와 시간, 그리고 이로부터 계산된 속도입니다. 사용자의 첫 확인에서는 null입니다.
previousLocation
이 호출 이전의 저장된 기준 위치에 대한 country, latitude, longitude, observedAt입니다. 사용자의 첫 확인에서는 null입니다.
currentLocation
이 호출에서 제공한 ip로부터 확인된 country, latitude, longitude입니다.

사전 확인 후 커밋하기

백엔드 cURL

# 자체 인증 결정에 앞선 사변적인 확인 — 기준 위치를 이동시키지 않습니다.
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}'

# 자체 비밀번호/2FA 검증이 성공한 뒤, 새로운 기준 위치를 커밋합니다.
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의 기본값은 true이므로 위의 두 번째 호출은 저장된 기준 위치를 갱신합니다. commit: false를 사용한 첫 번째 호출은 갱신하지 않습니다.

자주 묻는 질문

첫 확인에서는 어떻게 되나요?

항상 previousLocation이 null인 risk: "low"를 반환합니다 — 현재 위치와 비교할 대상이 아직 없기 때문입니다.

VPN 전환을 억제하나요?

아닙니다. v1에는 VPN이나 데이터센터를 고려한 억제 기능이 없으므로, 로그인 사이에 네트워크나 VPN 출구를 전환하는 것만으로도 medium 또는 high 결과가 발생할 수 있습니다.

high 결과가 계정 탈취의 증거인가요?

아닙니다. 이는 단순한 거리 대 시간 계산입니다. 이를 독립적인 판정으로 취급하지 말고 자체 인증 증거와 결합하세요.

기준 위치 업데이트를 피할 수 있나요?

네 — commit: false를 전달하세요. 확인은 여전히 실행되고 결과를 반환하지만, 저장된 위치는 교체되지 않습니다.

이전 위치는 얼마나 오래 보관되나요?

해당 userId에 대한 다음 커밋된 확인이 덮어쓸 때까지 무기한 보관됩니다 — 현재 구현에는 자동 만료나 삭제 엔드포인트가 없습니다.

관련 페이지