Skip to content

API Reference

Anti-Fraud API

A browser SDK for identification, signed webhooks for real-time events, and a read-only Server API for history. Everything you need to stop fraud at the device level.

Get API KeyAPI Playground

Endpoints

SDK@tracio/sdk

Identify a visitor in the browser with the client SDK. Returns a stable visitor ID and bot verdict with no server round-trip. The public key is safe to ship in client-side code.

Request

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

Response

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}
POST/webhook/tracio

TRACIO delivers a signed event to your endpoint on every identification. Verify the X-Tracio-Signature header, then act on the flat JSON payload. This is the push surface: you do not have to poll for it. If you do need to read a visit after the fact, the Server API answers by requestId.

Request

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...

Response

{
  "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

Fetch the platform Ed25519 public keys used to verify webhook deliveries. This route needs no authentication and is cached for five minutes. The kid in the signature header tells you which key to use.

Request

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

Response

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}
GET/v1/visitors/{visitorId}

Read a visitor's history from the Server API with your secret key. Available from the Pro plan. The window is clamped to your plan and the window you actually got is reported back in meta. Backs GDPR right-of-access requests.

Request

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

Response

{
  "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"
  }
}

Authentication

TRACIO uses three credentials, one per surface: a public key for the browser SDK, a secret key (tracio_sk_…) sent as Authorization: Bearer for the Server API, and an HMAC signing secret to verify webhook deliveries. The secret key is created in the dashboard, shown once, and must never reach a browser — the Server API deliberately returns no CORS headers.

# 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>

Rate Limits

Limits are per workspace. Server API calls are counted separately from identifications, so reading your own history never spends the quota you pay for. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, plus Retry-After on a 429. The Server API is not part of the Free plan.

PlanServer API rateServer API per dayWebhook endpointsQuery window
FreeNot includedNot included07 days
Pro10 req/s10,000530 days
Business50 req/s100,0002090 days
Enterprise200 req/sUnlimited100365 days

Error Codes

Every error returns the same envelope: an error object with a string code, a human-readable message, and the requestId of the failed call.

400Bad RequestMalformed query parameters, an unsupported window, or an identifier that is not a valid visitor ID.
401UnauthorizedMissing or invalid credentials — public key (SDK), secret key (Server API), or webhook signature.
402Upgrade RequiredYour plan does not include Server API access. It starts on the Pro plan.
404Not FoundNo visitor or session with that identifier inside your plan's query window.
405Method Not AllowedThe Server API is read-only. Every route answers GET and nothing else.
429Rate LimitedToo many requests per second, or the daily quota is spent. Check the Retry-After header and your plan limits.
500Internal ErrorServer error. Retry with exponential backoff. If it persists, contact support with the requestId.
503Service UnavailableThe API is temporarily unable to answer. Retry with exponential backoff.

Error Response Format

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

Start Building

Get your API key and make your first identification request in under 5 minutes.

Get API KeyFull API Docs