Récupérer les datapoints

Le navigateur n’a pas besoin de savoir ce que sendClientTelemetry(externalIds?) envoie en interne. Appelez la fonction, lisez le token de session renvoyé et laissez votre backend échanger ce token de session avec https://api.cside.com/token/v2/verify pour récupérer les datapoints de fingerprint, bot, navigateur, appareil, IP et environnement.

Flux de bout en bout

1. Le navigateur appelle sendClientTelemetry(externalIds?).
2. sendClientTelemetry envoie la télémétrie au CLIENT_URL configuré, généralement /client.
3. /client renvoie un JSON de la forme { "token": "..." }, où token est le token de session de fingerprint.
4. Votre backend envoie ce token de session à https://api.cside.com/token/v2/verify avec une clé API de Device Intelligence côté serveur.

Utiliser sendClientTelemetry

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

if (result.errors) {
  console.error(result.errors);
  throw new Error("La requête de télémétrie a échoué.");
}

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("Aucun token de session de fingerprint renvoyé.");
}

Après avoir extrait sessionToken, envoyez-le à votre backend. Votre backend effectue l’échange du token de session avec cside.

Vous pouvez aussi appeler sendClientTelemetry() sans argument. Utilisez externalIds uniquement lorsque vous voulez associer vos propres identifiants, comme accountId, orderId ou email, au fingerprint.

Détection de fraude avec les quatre derniers chiffres de carte

Un cas d’usage courant de fraude au checkout consiste à détecter un fingerprint d’appareil qui tente de payer avec de nombreuses cartes différentes. Vous pouvez associer les quatre derniers chiffres de la carte de paiement comme autre identifiant externe, puis examiner l’activité de fingerprint obtenue depuis votre backend.

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

Envoyez uniquement les quatre derniers chiffres. N’envoyez pas le numéro complet de la carte, le CVC, la date d’expiration ni d’autres données brutes de carte de paiement via externalIds.

Options de récupération

Méthode	Statut	Idéal pour
API	Disponible	Décisions à la requête et enrichissement backend
Export S3	Disponible lorsque configuré	Analyse batch, data warehouse et revue offline
Webhook	Non disponible	Livraison push vers les systèmes internes
WebSocket	Non disponible	Flux live et tableaux de bord presque temps réel

Générer une clé API backend

Générez une clé API de Device Intelligence dans le dashboard cside avant d’appeler l’endpoint authentifié. La clé commence par cside_tgatv1_, elle est affichée une seule fois et doit être stockée dans le gestionnaire de secrets de votre backend.

La clé API est une identité backend associée à l’équipe. Ne l’envoyez pas au navigateur, ne l’exposez pas dans des bundles frontend et ne l’écrivez pas dans du HTML depuis un Worker.

Récupération API avec le token de session

Le token de session ne contient pas le payload fingerprint complet. Utilisez-le comme token de lookup depuis votre backend avec l’endpoint cside authentifié.

Utilisez /token/v2/verify lorsque vous avez besoin du payload JSON complet depuis une intégration server-to-server.

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

L’endpoint renvoie 202 Accepted avec { "status": "pending" } tant que l’évaluation est en cours. Il renvoie 200 OK avec le payload terminé une fois l’enrichissement fini.

Exemple de requête backend :

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 || "La recherche de fingerprint a échoué.");
}

La réponse terminée inclut status, created_at, updated_at et les champs d’enrichissement disponibles, comme vpn_evaluation, fingerprint, geo_data, ip_enrichment, bot, network_client_metrics et fingerprint_enrichment.

Récupérez les évaluations précédentes du même appareil

Utilisez /token/v2/device/entries lorsque vous avez besoin des évaluations terminées associées au même ID d’appareil que le token de session. C’est utile pour le scoring de risque de compte, les files de revue de fraude, les enquêtes d’abus et pour relier une nouvelle session à une activité récente du même fingerprint de navigateur.

L’endpoint utilise la même clé API de Device Intelligence réservée au backend que /token/v2/verify. Il renvoie les résultats du plus récent au plus ancien et prend en charge la pagination avec limit et 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
  }'

Body de la requête

Champ	Type	Obligatoire	Description
token	string	Oui	Token de session renvoyé par sendClientTelemetry.
limit	number	Non	Nombre maximal d’entrées à renvoyer. La valeur par défaut est 500 et la limite maximale est 500.
offset	number	Non	Nombre d’entrées à ignorer à partir du résultat le plus récent. La valeur par défaut est 0. Utilisez le next_offset de la réponse précédente pour demander la page suivante.

Body de la réponse

La réponse contient le device_id résolu, un tableau entries et les métadonnées de pagination. Chaque entrée utilise la même forme de payload plat que /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
}

Champ	Type	Description
device_id	string	ID d’appareil résolu depuis le token de session.
entries	array	Évaluations terminées pour cet ID d’appareil, triées de la plus récente à la plus ancienne.
limit	number	Taille de page effective après limitation côté serveur.
offset	number	Offset utilisé pour cette réponse.
next_offset	number | null	Offset à envoyer dans la requête suivante. null signifie qu’il n’y a plus d’entrées.
has_more	boolean	true lorsqu’une autre page est disponible.

Exemple backend

Utilisez next_offset depuis la réponse au lieu de calculer les offsets vous-même. Arrêtez-vous lorsque has_more vaut false.

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 || "La recherche des entrées de l'appareil a échoué.");
    }

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

  return entries;
}

Si vous avez seulement besoin de la première page, omettez limit et offset. L’API renvoie jusqu’à 500 évaluations terminées par défaut.

Endpoints publics de token

/token/v1/client et /token/v1/clientId restent disponibles pour les intégrations qui ont spécifiquement besoin du flux de lookup public non authentifié.

Utilisez /token/v1/client lorsque vous avez besoin du payload JSON public sans authentification par clé API.

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

Utilisez /token/v1/clientId lorsque vous avez seulement besoin de l’ID stable de fingerprint.

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

Pour /token/v1/*, envoyez le token de session brut dans le body de la requête et ne l’enveloppez pas dans du JSON. L’endpoint clientId renvoie du texte brut. Si aucun ID de fingerprint n’existe pour le token de session, il renvoie 404.

Export S3

cside peut exporter les enregistrements de fingerprint vers S3 lorsque l’export fingerprint S3 est configuré pour un domaine. Utilisez-le pour les workflows batch qui ne nécessitent pas de décision à la requête.

Chaque enregistrement exporté est l’évaluation complète, pas un résumé : les champs d’identité, le fingerprint complet de l’appareil et les signaux réseau, IP, géo, VPN, bot et de règles que cside a calculés pour cette visite. Consultez le guide de l’export S3 pour les étapes de configuration et la structure complète d’un enregistrement.

Webhooks et flux WebSocket

Ni l’un ni l’autre n’est disponible. S3 est la seule destination d’export pour les données Device Intelligence, et aucun réglage au niveau du compte n’active la livraison webhook ou WebSocket.

Si vous avez besoin des données en dehors d’une fenêtre batch, appelez l’API à la requête.