Zum Inhalt springen

API-Referenz

Anti-Fraud-API

Ein Browser-SDK für die Identifikation, signierte Webhooks für Echtzeit-Events und eine nur lesende Server API für die Historie. Alles, was Sie brauchen, um Betrug auf Geräteebene zu stoppen.

API-Schlüssel erhaltenAPI-Playground

Endpunkte

SDK@tracio/sdk

Identifizieren Sie einen Besucher im Browser mit dem Client-SDK. Gibt eine stabile Besucher-ID und ein Bot-Verdict ohne Server-Roundtrip zurück. Der öffentliche Schlüssel kann gefahrlos in clientseitigem Code ausgeliefert werden.

Anfrage

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

Antwort

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

TRACIO liefert bei jeder Identifikation ein signiertes Event an Ihren Endpunkt. Verifizieren Sie den Header X-Tracio-Signature und reagieren Sie dann auf die flache JSON-Payload. Dies ist die Push-Schnittstelle: Sie müssen dafür nicht pollen. Wenn Sie einen Besuch doch im Nachhinein lesen müssen, antwortet die Server API per requestId.

Anfrage

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

Antwort

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

Rufen Sie die öffentlichen Ed25519-Schlüssel der Plattform ab, mit denen Webhook-Zustellungen verifiziert werden. Diese Route benötigt keine Authentifizierung und wird fünf Minuten lang gecacht. Die kid im Signatur-Header sagt Ihnen, welcher Schlüssel zu verwenden ist.

Anfrage

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

Antwort

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

Lesen Sie die Historie eines Besuchers über die Server API mit Ihrem Secret Key. Verfügbar ab dem Pro-Tarif. Das Fenster wird auf Ihren Tarif begrenzt, und das tatsächlich gelieferte Fenster wird in meta zurückgemeldet. Unterstützt Auskunftsersuchen (Auskunftsrecht) nach der DSGVO.

Anfrage

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

Antwort

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

Authentifizierung

TRACIO verwendet drei Arten von Anmeldedaten, je eine pro Schnittstelle: einen öffentlichen Schlüssel für das Browser-SDK, einen Secret Key (tracio_sk_…), der als Authorization: Bearer an die Server API gesendet wird, und ein HMAC-Signing-Secret zur Verifikation von Webhook-Zustellungen. Der Secret Key wird im Dashboard erstellt, einmalig angezeigt und darf niemals in einen Browser gelangen — die Server API gibt bewusst keine CORS-Header zurück.

# 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

Die Limits gelten pro Workspace. Aufrufe der Server API werden getrennt von Identifikationen gezählt, sodass das Lesen der eigenen Historie nie das Kontingent verbraucht, für das Sie zahlen. Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset, bei einem 429 zusätzlich Retry-After. Die Server API ist nicht Teil des Free-Tarifs.

TarifServer-API-RateServer API pro TagWebhook-EndpunkteAbfragefenster
FreeNicht enthaltenNicht enthalten07 days
Pro10 req/s10,000530 days
Business50 req/s100,0002090 days
Enterprise200 req/sUnbegrenzt100365 days

Fehlercodes

Jeder Fehler kommt im selben Rahmen zurück: ein error-Objekt mit einem code als String, einer menschenlesbaren message und der requestId des fehlgeschlagenen Aufrufs.

400Bad RequestFehlerhafte Query-Parameter, ein nicht unterstütztes Fenster oder ein Identifikator, der keine gültige Besucher-ID ist.
401UnauthorizedFehlende oder ungültige Anmeldedaten — öffentlicher Schlüssel (SDK), Secret Key (Server API) oder Webhook-Signatur.
402Upgrade RequiredIhr Tarif enthält keinen Zugriff auf die Server API. Er beginnt mit dem Pro-Tarif.
404Not FoundKein Besucher und keine Sitzung mit diesem Identifikator im Abfragefenster Ihres Tarifs.
405Method Not AllowedDie Server API ist nur lesend. Jede Route beantwortet GET und sonst nichts.
429Rate LimitedZu viele Anfragen pro Sekunde, oder das Tageskontingent ist aufgebraucht. Prüfen Sie den Header Retry-After und die Limits Ihres Tarifs.
500Internal ErrorServerfehler. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Bei anhaltendem Fehler wenden Sie sich mit der requestId an den Support.
503Service UnavailableDie API kann vorübergehend nicht antworten. Wiederholen Sie den Vorgang mit exponentiellem Backoff.

Format der Fehlerantwort

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

Jetzt entwickeln

Holen Sie sich Ihren API-Schlüssel und senden Sie Ihre erste Identifikationsanfrage in unter 5 Minuten.

API-Schlüssel erhaltenVollständige API-Dokumentation