API-referentie

Anti-fraude-API

Een browser-SDK voor identificatie, ondertekende webhooks voor realtime events, en een alleen-lezen Server API voor geschiedenis. Alles wat je nodig hebt om fraude op apparaatniveau te stoppen.

API-sleutel verkrijgen API Playground

Endpoints

SDK@tracio/sdk

Identificeer een bezoeker in de browser met de client-SDK. Retourneert een stabiele bezoekers-ID en botverdict zonder server-round-trip. De public key kan veilig in client-side code worden meegeleverd.

Verzoek

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 levert een ondertekend event aan je endpoint bij elke identificatie. Verifieer de X-Tracio-Signature-header en handel vervolgens op basis van de platte JSON-payload. Dit is het push-oppervlak: je hoeft er niet naar te pollen. Moet je een bezoek toch achteraf lezen, dan antwoordt de Server API op requestId.

Verzoek

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

Haal de publieke Ed25519-sleutels van het platform op waarmee webhook-leveringen worden geverifieerd. Deze route vereist geen authenticatie en wordt vijf minuten gecacht. De kid in de signature-header vertelt je welke sleutel je moet gebruiken.

Verzoek

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

Response

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

GET/v1/visitors/{visitorId}

Lees de geschiedenis van een bezoeker uit de Server API met je secret key. Beschikbaar vanaf het Pro-abonnement. Het venster wordt begrensd door je abonnement en het venster dat je werkelijk kreeg wordt teruggemeld in meta. Ondersteunt inzageverzoeken onder de AVG (GDPR).

Verzoek

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

Authenticatie

TRACIO gebruikt drie credentials, één per oppervlak: een public key voor de browser-SDK, een secret key (tracio_sk_…) die als Authorization: Bearer wordt meegestuurd voor de Server API, en een HMAC signing secret om webhook-leveringen te verifiëren. De secret key wordt in het dashboard aangemaakt, eenmalig getoond en mag nooit in een browser terechtkomen — de Server API geeft bewust geen CORS-headers terug.

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

Ratelimieten

Limieten gelden per workspace. Server API-calls worden apart geteld van identificaties, dus het lezen van je eigen geschiedenis kost nooit het quotum waarvoor je betaalt. Elke response bevat X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset, plus Retry-After bij een 429. De Server API maakt geen deel uit van het gratis abonnement.

Abonnement	Server API per seconde	Server API per dag	Webhook-endpoints	Queryvenster
Gratis	Niet inbegrepen	Niet inbegrepen	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	Onbeperkt	100	365 days

Foutcodes

Elke fout retourneert dezelfde envelope: een error-object met een string-code, een leesbaar message-veld en de requestId van de mislukte call.

400Bad RequestVerkeerd opgemaakte queryparameters, een niet-ondersteund venster, of een identificator die geen geldig bezoekers-ID is.

401UnauthorizedOntbrekende of ongeldige credentials — public key (SDK), secret key (Server API), of webhook-handtekening.

402Upgrade RequiredJe abonnement bevat geen toegang tot de Server API. Die begint bij het Pro-abonnement.

404Not FoundGeen bezoeker of sessie met die identificator binnen het queryvenster van je abonnement.

405Method Not AllowedDe Server API is alleen-lezen. Elke route beantwoordt GET en verder niets.

429Rate LimitedTe veel verzoeken per seconde, of het dagquotum is op. Controleer de Retry-After-header en je abonnementslimieten.

500Internal ErrorServerfout. Probeer opnieuw met exponential backoff. Houdt het aan, neem dan contact op met support met de requestId.

503Service UnavailableDe API kan tijdelijk niet antwoorden. Probeer opnieuw met exponential backoff.

Formaat van foutresponse

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

Begin met bouwen

Vraag je API-sleutel aan en doe je eerste identificatieverzoek in minder dan 5 minuten.

API-sleutel verkrijgen Volledige API-documentatie