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

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	Planifié ou activé par compte	Livraison push vers les systèmes internes
WebSocket	Planifié ou activé par compte	Flux live et tableaux de bord presque temps réel

Générer une clé API backend

Générez une clé API de fingerprint 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 fingerprint 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.

Les enregistrements exportés incluent le transaction ID, le domaine client, le timestamp, la référence client et l’identifiant de fingerprint.

Webhooks

La livraison webhook est planifiée ou activée pour certains comptes. Utilisez les webhooks lorsque votre système doit recevoir les nouveaux datapoints sans interroger l’API.

Bons cas d’usage webhook :

• Envoyer les événements de fingerprint vers une file fraude
• Enrichir un SIEM ou pipeline de données
• Déclencher des workflows de revue pour les sessions suspectes

Flux WebSocket

La livraison WebSocket est planifiée ou activée pour certains comptes. Utilisez-la lorsque vous avez besoin d’un flux live pour dashboards, outils d’opérations ou investigations actives.