문서
가입 페이지에 에이전트를 넣고, 서버에서 엔드포인트 하나를 호출한 뒤, 판정에 따라 처리하세요.
빠른 시작
1. 가입 페이지에 에이전트 추가
기기 신호를 수집하고, 페이지의 모든 폼에 attrelix_visitor라는 숨은 필드로 수명이 짧은 방문자 토큰을 넣습니다. 싱글 페이지 앱을 위해 window.attrelix.token()도 제공합니다.
<script src="https://attrelix.com/v1.js?v=0bbe74b52d" data-key="pk_live_…" async></script> // single-page apps: wait for the token before you submit const visitor = await window.attrelix.token();
2. 서버에서 가입 검사
비밀 키와 함께 이메일, 클라이언트 IP, 방문자 토큰을 보내세요. 선택: external_id(자체 사용자 ID), user_agent, card_fingerprint(예: Stripe의 card.fingerprint).
curl https://attrelix.com/v1/check \ -H "Authorization: Bearer $ATTRELIX_SECRET" \ -H "Content-Type: application/json" \ -d '{"email":"jdoe+7@gmail.com","ip":"203.0.113.9","visitor":"vt1.…"}'
# Python r = requests.post("https://attrelix.com/v1/check", timeout=3, headers={"Authorization": f"Bearer {SECRET}"}, json={"email": email, "ip": ip, "visitor": form["attrelix_visitor"]}) decision = r.json().get("decision", "allow") if r.ok else "allow"
3. 판정에 따라 처리
allow: 무료 크레딧 지급. review: 카드나 전화번호처럼 작업장에 비용이 드는 것을 요구하거나 크레딧을 줄여 지급. block: 계정이나 크레딧을 거부. 호출이 실패하면 허용하세요. 저희 때문에 실제 사용자를 막아서는 안 됩니다.
키와 토큰
- 공개 키(pk_live_…): 공개를 전제로 한 키입니다. 페이지에 두며, 대시보드에서 허용한 오리진에서 신호를 수집하는 것만 할 수 있습니다.
- 비밀 키(sk_live_…): 서버 전용. 검사를 실행하고 결과를 읽습니다. 해시만 저장하므로 생성할 때 복사하세요.
- 방문자 토큰: 저희가 서명하며, 15분 동안 한 번의 검사에만 유효하고 프로젝트에 묶입니다. 두 번 쓰인 토큰이나 가입과 다른 네트워크에서 받은 토큰은 점수를 올립니다.
POST /v1/check
요청 본문(JSON). email, ip, visitor 중 하나 이상을 보내세요.
| 사용자가 입력한 주소. | |
| ip | 가입 요청의 클라이언트 IP(서버 IP가 아님). |
| visitor | 폼의 attrelix_visitor 값. |
| user_agent | 가입 요청의 User-Agent 헤더. |
| external_id | 계정이 이미 있을 때의 자체 ID. |
| card_fingerprint | 가입 시 카드를 등록한 경우의 카드 핑거프린트. |
응답
decision은 allow, review, block 중 하나입니다. score는 0~100으로, 이유별 점수의 합(상한 있음)입니다. 각 이유에는 기록하거나 표시할 수 있는 고정 코드가 있습니다.
{
"id": "chk_3fJ8kQ2mN7pX1aZb",
"decision": "block",
"score": 100,
"reasons": [
{ "code": "linked_accounts_10", "points": 45, "detail": "14" },
{ "code": "alias_of_existing", "points": 30, "detail": "3 variants of jdoe@gmail.com" },
{ "code": "datacenter_ip", "points": 25, "detail": "aws" }
],
"email": { "normalized": "jdoe@gmail.com", "disposable": false, "relay": false, "mx": "yes", … },
"network": { "ip": "3.88.0.1", "type": "datacenter", "provider": "aws", "signups_24h": 2 },
"device": { "id": "dev_9c1e…", "token": "valid", "browser": "Firefox 144", "flags": ["canvas_noise"] },
"linked": { "accounts": 14, "by_device": 12, "by_card": 0, "cluster": "cl_7q2f…" },
"latency_ms": 38
}
오류
오류는 JSON으로 반환됩니다: {"error": code, "message": text}.
| 401 | 키가 없거나, 알 수 없거나, 폐기됐거나, 종류가 틀림(/v1/check에 pk_ 키 사용). |
| 400 | 본문이 JSON이 아니거나 email, ip, visitor가 모두 없음. |
| 402 | 요금제의 월 검사 횟수를 모두 사용함. |
| 403 | 허용하지 않은 오리진에서 에이전트가 실행됨. |
| 429 | 한 주소에서 요청이 너무 많음. |
점수 계산
점수는 더해지며 최대 100입니다. 기본값은 50점부터 검토, 80점부터 차단이며 둘 다 조정할 수 있습니다. 일회용 메일함 하나만으로도 검토가 되지만, 기기나 네트워크 신호 하나만으로는 검토가 되지 않습니다.
| 코드 | 점수 | 의미 |
|---|---|---|
| invalid_email | +50 | 유효하지 않은 주소 |
| disposable_email | +50 | 일회용 이메일 도메인 |
| no_mx | +35 | 도메인이 메일을 받을 수 없음 |
| alias_of_existing | +30 | 이미 본 메일함의 다른 표기 |
| relay_email | +10 | 전달 서비스 주소 |
| plus_tag | +5 | + 태그 또는 Gmail 점 |
| tor_exit | +35 | Tor 출구 노드 |
| datacenter_ip | +25 | 데이터센터 또는 클라우드 주소 |
| vpn_ip | +20 | VPN 주소 |
| ip_signups_24h | +10 | 이 IP에서 24시간 내 3개 이상 |
| ip_signups_24h_high | +25 | 이 IP에서 24시간 내 10개 이상 |
| subnet_burst | +15 | 이 서브넷에서 1시간 내 10개 이상 |
| automation_webdriver | +40 | WebDriver 자동화 |
| headless_browser | +40 | 헤드리스 브라우저 |
| automation_cdp | +10 | DevTools 프로토콜 자동화(Puppeteer, Playwright) |
| antidetect_browser | +15 | 안티디텍트 브라우저(여러 위장이 동시에 존재) |
| headless_viewport | +15 | 브라우저 창 테두리와 탭이 없는 창 |
| webgl_os_mismatch | +25 | 그래픽 카드가 다른 운영체제의 것 |
| memory_cpu_mismatch | +10 | 코어 수와 메모리가 서로 맞지 않음 |
| no_human_interaction | +30 | 입력·마우스·터치 없이 즉시 전송 |
| instant_signup | +25 | 페이지 로딩 후 1초 안에 입력과 전송 완료 |
| os_mismatch | +20 | 운영체제 정보가 서로 모순됨 |
| browser_mismatch | +20 | 브라우저가 자신의 user agent와 모순됨 |
| fonts_mismatch | +15 | 글꼴이 주장하는 시스템과 맞지 않음 |
| canvas_noise | +15 | 무작위화된 canvas 핑거프린트 |
| software_renderer | +15 | 소프트웨어 그래픽(가상 머신 또는 헤드리스) |
| zero_window | +15 | 크기가 없는 창 |
| permissions_mismatch | +15 | 권한 상태가 서로 모순됨 |
| no_plugins | +10 | 플러그인 없는 데스크톱 Chrome |
| no_languages | +10 | 브라우저 언어 없음 |
| utc_timezone | +5 | 시계가 UTC |
| token_missing | 0–100 | 방문자 토큰 없음(에이전트 미로드 또는 차단) |
| token_invalid | +30 | 위조되었거나 다른 프로젝트의 방문자 토큰 |
| token_replayed | +35 | 이미 사용된 방문자 토큰 |
| token_expired | +10 | 만료된 방문자 토큰 |
| token_ip_mismatch | +8 | 다른 네트워크에서 받은 토큰 |
| token_ua_mismatch | +15 | 다른 브라우저에서 받은 토큰 |
| linked_accounts | +15 | 다른 계정과 연결됨 |
| linked_accounts_3 | +30 | 3개 이상 계정과 연결됨 |
| linked_accounts_10 | +45 | 10개 이상 계정과 연결됨 |
| shared_card | +30 | 다른 계정이 사용한 카드 |
| device_burst | +15 | 이 기기에서 1시간 내 5회 이상 검사 |
데이터 출처
일회용 도메인: disposable-email-domains 프로젝트(CC0)와 disposable/disposable-email-domains(MIT), 매일 갱신. 데이터센터 대역: AWS, Google Cloud, Oracle Cloud, DigitalOcean, Linode가 공개한 목록. Tor: Tor Project의 출구 노드 목록, 매시간 갱신.
현재: 일회용 도메인 98,644개, 대역 21,665개.