API 레퍼런스

안티프라우드 API

식별을 위한 브라우저 SDK, 실시간 이벤트를 위한 서명된 웹훅, 그리고 이력 조회를 위한 읽기 전용 Server API. 디바이스 수준에서 사기를 막는 데 필요한 모든 것.

엔드포인트

SDK@tracio/sdk

클라이언트 SDK로 브라우저에서 방문자를 식별합니다. 서버 왕복 없이 안정적인 방문자 ID와 봇 판정을 반환합니다. 공개 키는 클라이언트 측 코드에 포함해도 안전합니다.

요청

import { Tracio } from '@tracio/sdk'
const tracio = Tracio.init({ publicKey: '5ca175fc...' })
const result = await tracio.getResult()

응답

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

POST/webhook/tracio

TRACIO는 매 식별마다 서명된 이벤트를 여러분의 엔드포인트로 전달합니다. X-Tracio-Signature 헤더를 검증한 다음 평면(flat) JSON 페이로드에 따라 대응하세요. 이것은 푸시 채널이므로 폴링할 필요가 없습니다. 사후에 방문 기록을 읽어야 한다면 Server API가 requestId로 답합니다.

요청

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Payload-Version: 2
X-Tracio-Event-Type: identification
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

응답

{
  "version": 2,
  "event": "identification",
  "eventId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9:primary",
  "requestId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9",
  "phase": "primary",
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "timestamp": "2026-03-12T16:00:00Z",
  "bot": { "result": "human", "score": 2 },
  "identification": { "confidence": 0.95, "incognito": false },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "real", "riskScore": 4 }
}

GET/.well-known/webhook-keys

웹훅 전달을 검증하는 데 쓰이는 플랫폼 Ed25519 공개 키를 가져옵니다. 이 경로는 인증이 필요 없으며 5분 동안 캐시됩니다. 서명 헤더의 kid가 어떤 키를 사용해야 하는지 알려 줍니다.

요청

curl https://api.tracio.ai/.well-known/webhook-keys

응답

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}

GET/v1/visitors/{visitorId}

시크릿 키로 Server API에서 방문자의 이력을 읽습니다. Pro 플랜부터 사용할 수 있습니다. 조회 구간은 플랜에 맞게 제한되며, 실제로 받은 구간은 meta에 함께 보고됩니다. GDPR 열람권(right-of-access) 요청을 지원합니다.

요청

# Server API — available on the Pro plan and above
curl "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

응답

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-03-01T08:11:00Z",
  "lastSeenAt": "2026-03-16T14:22:01Z",
  "visits": 12,
  "incognitoVisits": 1,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "risk": { "maxRiskScore": 63, "lastDecision": "real" },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true
  },
  "meta": {
    "plan": "pro",
    "retentionDays": 30,
    "from": "2026-02-14T00:00:00Z",
    "to": "2026-03-16T14:30:00Z"
  }
}

인증

TRACIO는 연동 지점마다 하나씩, 세 가지 자격 증명을 사용합니다: 브라우저 SDK용 공개 키, Server API용으로 Authorization: Bearer에 실어 보내는 시크릿 키(tracio_sk_…), 그리고 웹훅 전달을 검증하기 위한 HMAC 서명 시크릿입니다. 시크릿 키는 대시보드에서 생성되어 한 번만 표시되며 절대 브라우저에 도달해서는 안 됩니다 — Server API는 의도적으로 CORS 헤더를 반환하지 않습니다.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Server API — secret key, created in the dashboard and shown once
Authorization: Bearer tracio_sk_XXXX...XXXX
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

속도 제한

제한은 워크스페이스별로 적용됩니다. Server API 호출은 식별과 별도로 집계되므로, 자기 이력을 읽는 데 결제한 할당량이 소모되지 않습니다. 모든 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 포함되며, 429일 때는 Retry-After가 추가됩니다. Server API는 Free 플랜에 포함되지 않습니다.

플랜	Server API 속도	일일 Server API	웹훅 엔드포인트	조회 구간
무료	미포함	미포함	0	7 days
Pro	10 req/s	10,000	5	30 days
Business	50 req/s	100,000	20	90 days
Enterprise	200 req/s	무제한	100	365 days

오류 코드

모든 오류는 동일한 봉투(envelope)로 반환됩니다: 문자열 code, 사람이 읽을 수 있는 message, 그리고 실패한 호출의 requestId를 담은 error 객체입니다.

400Bad Request잘못된 형식의 쿼리 파라미터, 지원되지 않는 조회 구간, 또는 유효한 방문자 ID가 아닌 식별자.

401Unauthorized자격 증명 누락 또는 유효하지 않음 — 공개 키(SDK), 시크릿 키(Server API), 또는 웹훅 서명.

402Upgrade Required현재 플랜에는 Server API 접근이 포함되어 있지 않습니다. Pro 플랜부터 제공됩니다.

404Not Found플랜의 조회 구간 안에 해당 식별자를 가진 방문자나 세션이 없습니다.

405Method Not AllowedServer API는 읽기 전용입니다. 모든 경로는 GET에만 응답합니다.

429Rate Limited초당 요청이 너무 많거나 일일 할당량을 모두 사용했습니다. Retry-After 헤더와 플랜 제한을 확인하세요.

500Internal Error서버 오류. 지수 백오프로 재시도하세요. 계속되면 requestId와 함께 지원팀에 문의하세요.

503Service UnavailableAPI가 일시적으로 응답할 수 없습니다. 지수 백오프로 재시도하세요.

오류 응답 형식

{
  "error": {
    "code": "rate_limited",
    "message": "too many requests",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

개발 시작하기

API 키를 발급받고 5분 이내에 첫 식별 요청을 실행하세요.

API 키 발급받기 전체 API 문서