Datapoints ophalen

De browser hoeft niet te weten welke payload sendClientTelemetry(externalIds?) verstuurt. Roep de functie aan, lees het geretourneerde sessietoken, en laat uw backend dat sessietoken uitwisselen met https://api.cside.com/token/v2/verify om fingerprint-, bot-, browser-, apparaat-, IP- en omgevingsdatapoints op te halen.

End-to-end flow

1. De browser roept sendClientTelemetry(externalIds?) aan.
2. sendClientTelemetry verzendt telemetry naar het geconfigureerde CLIENT_URL, meestal /client.
3. /client retourneert JSON in de vorm { "token": "..." }, waarbij token het fingerprint-sessietoken is.
4. Uw backend stuurt dat sessietoken naar https://api.cside.com/token/v2/verify met een server-side Device Intelligence API-sleutel.

sendClientTelemetry gebruiken

const result = await sendClientTelemetry({
  email: "user@example.com",
  accountId: "1234567890",
});

if (result.errors) {
  console.error(result.errors);
  throw new Error("Telemetry-aanvraag is mislukt.");
}

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("Geen fingerprint-sessietoken ontvangen.");
}

Nadat u sessionToken hebt uitgehaald, stuurt u het naar uw backend. Uw backend voert de tokenuitwisseling met cside uit.

U kunt sendClientTelemetry() ook zonder argumenten aanroepen. Gebruik externalIds alleen wanneer u eigen identifiers, zoals accountId, orderId of email, aan de fingerprint wilt koppelen.

Fraudedetectie met de laatste vier cijfers van de kaart

Een veelvoorkomende checkout-fraudecase is het detecteren van een apparaatfingerprint die met veel verschillende kaarten probeert te betalen. U kunt de laatste vier cijfers van de betaalkaart als extra externe identifier koppelen en daarna de resulterende fingerprintactiviteit vanuit uw backend bekijken.

const result = await sendClientTelemetry({
  accountId: "1234567890",
  orderId: "order-456",
  cardLast4: "4242",
});

Stuur alleen de laatste vier cijfers. Stuur geen volledig kaartnummer, CVC, vervaldatum of andere ruwe betaalkaartgegevens via externalIds.

Ophaalopties

Methode	Status	Best voor
API	Beschikbaar	Beslissingen tijdens requests en backendverrijking
S3-export	Beschikbaar wanneer ingeschakeld	Batchanalyse, warehousing en offline review
Webhook	Niet beschikbaar	Pushlevering naar interne systemen
WebSocket	Niet beschikbaar	Live streams en bijna-realtime dashboards

Genereer een backend-API-sleutel

Genereer een Device Intelligence API-sleutel in het cside-dashboard voordat u het geauthenticeerde endpoint aanroept. De sleutel begint met cside_tgatv1_, wordt maar één keer getoond en moet in de secretmanager van uw backend worden opgeslagen.

De API-sleutel is een teamgebonden backendcredential. Stuur deze niet naar de browser, exposeer deze niet in frontendbundles en schrijf deze niet vanuit een Worker naar HTML.

API ophalen met het sessietoken

Het sessietoken zelf bevat niet de volledige fingerprintdata. Gebruik het als lookup-token vanuit uw backend met het geauthenticeerde cside-endpoint.

Gebruik /token/v2/verify wanneer u de volledige JSON-payload nodig heeft vanuit een server-to-serverintegratie.

curl https://api.cside.com/token/v2/verify \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"token":"'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'"}'

Het endpoint retourneert 202 Accepted met { "status": "pending" } zolang de evaluatie nog wordt verwerkt. Het retourneert 200 OK met de voltooide payload zodra verrijking klaar is.

Voorbeeld van een backendrequest:

const csideResponse = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token: sessionToken }),
});

const datapoints = await csideResponse.json();

if (!csideResponse.ok) {
  throw new Error(datapoints.error_message || "Fingerprintlookup is mislukt.");
}

De voltooide response bevat status, created_at, updated_at en beschikbare verrijkingsvelden, zoals vpn_evaluation, fingerprint, geo_data, ip_enrichment, bot, network_client_metrics en fingerprint_enrichment.

Eerdere evaluaties voor hetzelfde apparaat ophalen

Gebruik /token/v2/device/entries wanneer u voltooide evaluaties nodig heeft die bij dezelfde device-ID horen als het sessietoken. Dit is nuttig voor accountrisicoscores, fraudereviewwachtrijen, onderzoek naar misbruik en het koppelen van een nieuwe sessie aan recente activiteit van dezelfde browserfingerprint.

Het endpoint gebruikt dezelfde backend-only Device Intelligence API-sleutel als /token/v2/verify. Het retourneert resultaten van nieuw naar oud en ondersteunt paginering met limit en offset.

curl https://api.cside.com/token/v2/device/entries \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "token": "'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'",
    "limit": 100,
    "offset": 0
  }'

Requestbody

Veld	Type	Verplicht	Beschrijving
token	string	Ja	Sessietoken dat door sendClientTelemetry is geretourneerd.
limit	number	Nee	Maximumaantal entries om te retourneren. De standaardwaarde is 500 en de maximale waarde is 500.
offset	number	Nee	Aantal entries dat vanaf het nieuwste resultaat wordt overgeslagen. De standaardwaarde is 0. Gebruik de next_offset uit de vorige response om de volgende pagina op te vragen.

Responsebody

De response bevat de opgeloste device_id, een entries-array en pagineringsmetadata. Elke entry gebruikt dezelfde vlakke payloadvorm als /token/v2/verify.

{
  "device_id": "a1b2c3d4e5f6...",
  "entries": [
    {
      "status": "completed",
      "created_at": 1779441600000,
      "updated_at": 1779441600000,
      "fingerprint": {},
      "network_client_metrics": {}
    }
  ],
  "limit": 100,
  "offset": 0,
  "next_offset": 100,
  "has_more": true
}

Veld	Type	Beschrijving
device_id	string	Device-ID die uit het sessietoken is opgelost.
entries	array	Voltooide evaluaties voor die device-ID, gesorteerd van nieuw naar oud.
limit	number	Effectieve paginagrootte na server-side begrenzing.
offset	number	Offset die voor deze response is gebruikt.
next_offset	number | null	Offset die u in de volgende request moet meesturen. null betekent dat er geen entries meer zijn.
has_more	boolean	true wanneer er nog een pagina beschikbaar is.

Backendvoorbeeld

Gebruik next_offset uit de response in plaats van offsets zelf te berekenen. Stop wanneer has_more false is.

async function fetchDeviceEntries(sessionToken) {
  const entries = [];
  let offset = 0;
  const limit = 100;

  while (offset !== null) {
    const response = await fetch("https://api.cside.com/token/v2/device/entries", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        token: sessionToken,
        limit,
        offset,
      }),
    });

    const page = await response.json();

    if (!response.ok) {
      throw new Error(page.error || "Lookup van device entries is mislukt.");
    }

    entries.push(...page.entries);
    offset = page.has_more ? page.next_offset : null;
  }

  return entries;
}

Als u alleen de eerste pagina nodig heeft, laat u limit en offset weg. De API retourneert standaard maximaal 500 voltooide evaluaties.

Publieke token-endpoints

/token/v1/client en /token/v1/clientId blijven beschikbaar voor integraties die specifiek de niet-geauthenticeerde publieke lookupflow nodig hebben.

Gebruik /token/v1/client wanneer u de publieke JSON-payload zonder API-sleutelauthenticatie nodig heeft.

curl https://api.cside.com/token/v1/client \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Gebruik /token/v1/clientId wanneer u alleen de stabiele fingerprint-ID nodig heeft.

curl https://api.cside.com/token/v1/clientId \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Voor /token/v1/* stuurt u het ruwe sessietoken in de request body en verpakt u het niet in JSON. Het clientId-endpoint retourneert platte tekst. Als er geen fingerprint-ID voor het sessietoken bestaat, retourneert het 404.

S3-export

cside kan fingerprintrecords exporteren naar S3 wanneer fingerprint S3-export is geconfigureerd voor een domein. Gebruik dit voor batchworkflows waar je geen beslissing tijdens een request nodig hebt.

Elk geëxporteerd record is de volledige evaluatie, geen samenvatting: de identiteitsvelden, de volledige apparaatvingerafdruk en de netwerk-, IP-, geo-, VPN-, bot- en regelsignalen die cside voor dat bezoek heeft berekend. Zie de handleiding voor de S3-export voor de stappen om het in te stellen en de volledige recordstructuur.

Webhooks en WebSocket-streams

Geen van beide is beschikbaar. S3 is de enige exportbestemming voor Device Intelligence-gegevens, en er is geen instelling op accountniveau die webhook- of WebSocketlevering inschakelt.

Heb je gegevens nodig buiten een batchvenster om, roep dan de API aan tijdens het request.