> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signaux de risque

> Ingérer les signaux de détection de fraude de n'importe quelle source, normaliser les événements d'identité en signaux scorés, et les interroger par entité, score ou type.

Les signaux de risque vous permettent d'intégrer des données de détection de fraude dans Truthlocks depuis n'importe quel fournisseur en amont — services d'empreintes digitales d'appareils, API de réputation IP, outils de vérification d'e-mails, moteurs d'analyse de documents ou vos propres règles internes. Une fois ingérés, les signaux sont disponibles via l'API et la page **Risque et Fraude > Signaux** dans la console.

> [!NOTE]
>
> Le pare-feu d'identité anti-fraude est **généralement disponible**. Les cinq chemins de détection — ingestion directe de signaux, normalisation d'événements, analyse de deepfake, détection d'ATO et score de vélocité — sont intégrés avec des exemples d'API multilingues (cURL, JavaScript, Python), des guides de bout en bout et des [notifications webhook](https://docs.truthlocks.com/fr/guides/webhooks.md) en temps réel pour tous les types de signaux. Les [décisions de risque](https://docs.truthlocks.com/fr/api-reference/risk/evaluate.md) automatisées, la [gestion de cas](#case-management) et l'[exportation SIEM de fraude](#siem-export) sont désormais disponibles.

Vous pouvez créer des signaux de cinq manières :

* **Ingestion directe** — envoyez un signal entièrement noté via `POST /v1/risk/signals` lorsque vous avez déjà un score de risque d'un fournisseur externe. Prend en charge les tentatives idempotentes via l'en-tête `Idempotency-Key`.
* **Normalisation des événements** — envoyez un événement d'identité brut via `POST /v1/risk/events` et laissez la plateforme le mapper automatiquement à un type de signal et à un score de base. Voir [normalisation des événements](#event-normalization).
* **Notation des signaux de deepfake et d'usurpation d'identité** — soumettez des indicateurs ou des scores produits en externe pour évaluation du seuil via `POST /v1/risk/deepfake/scan`. Les scans qui obtiennent un score de 60 ou plus ingèrent automatiquement un signal de risque. Consultez le [guide de détection de deepfake](https://docs.truthlocks.com/fr/guides/deepfake-detection.md).
* **Détection de prise de contrôle de compte** — évalue les événements de connexion par rapport aux heuristiques basées sur la vélocité via `POST /v1/risk/ato/evaluate`. Des alertes sont créées et des signaux de risque sont ingérés automatiquement lorsque les seuils sont dépassés. Voir le [guide de détection ATO](https://docs.truthlocks.com/fr/guides/ato-detection.md).
* **Notation de vélocité et d'anomalie** — enregistrez les actions du sujet via `POST /v1/risk/velocity/record` et laissez la plateforme suivre la fréquence sur des fenêtres de temps glissantes (1 m, 5 m, 1 h, 24 h). Les actions qui produisent un score de vélocité pondéré de 60 ou plus ingèrent automatiquement un signal de risque. Voir le [guide de notation de vélocité](https://docs.truthlocks.com/fr/guides/velocity-scoring.md).

### Choisir un chemin d'ingestion

| Scénario | Utilisation | Point de terminaison |
| :- | :- | :- |
| Vous avez un score de risque provenant d'un outil de fraude externe | Ingestion directe | `POST /v1/risk/signals` |
| Vous souhaitez que les événements natifs de la plateforme (échecs de connexion, détections de deepfake) soient automatiquement notés | Normalisation des événements | `POST /v1/risk/events` |
| Vous souhaitez noter les indicateurs de deepfake ou d'usurpation d'identité fournis | Analyse de deepfake | `POST /v1/risk/deepfake/scan` |
| Vous souhaitez détecter les tentatives de prise de contrôle de compte basées sur la vélocité de connexion | Détection ATO | `POST /v1/risk/ato/evaluate` |
| Vous souhaitez détecter les anomalies de vélocité pour tout type d'action | Notation de vélocité | `POST /v1/risk/velocity/record` |
| Vous utilisez plusieurs sources de signaux | Les cinq — les signaux arrivent dans le même pipeline | N'importe quel point de terminaison |

Les cinq chemins produisent les mêmes enregistrements de signaux de risque. Vous pouvez interroger, filtrer et examiner les signaux de n'importe quel chemin à l'aide du [point de terminaison de liste](https://docs.truthlocks.com/fr/api-reference/risk-signals/list.md) et de la page de la console **Risque et fraude > Signaux**.

## Comment ça marche

**1. Ingérer les signaux**

Envoyez une requête `POST` à `/v1/risk/signals` avec la source du signal, le type, le score de risque et le sujet auquel il se rapporte. Joignez tout contexte supplémentaire dans l'objet `payload`.

**2. Interroger et filtrer**

Utilisez `GET /v1/risk/signals` pour lister les signaux avec des filtres pour la source, le type de signal, le sujet et le score minimum. Les résultats sont paginés avec une pagination basée sur un curseur.

**3. Examiner dans la console**

Ouvrez **Risque et Fraude > Signaux** dans la console du locataire pour parcourir les signaux, filtrer par source ou score, et inspecter les détails de chaque signal.

## Prérequis

* Un locataire Truthlocks actif avec une clé API
* Au moins une source de détection de fraude en amont qui produit des signaux notés

## Ingestion d'un signal

Envoyez une requête `POST` avec les champs requis :

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/signals \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "signal_source": "external",
    "signal_type": "velocity",
    "risk_score": 85,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f",
    "payload": {
      "ip": "203.0.113.42",
      "country": "US",
      "reason": "multiple_accounts_same_device"
    },
    "ip_address": "203.0.113.42"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/signals", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    signal_source: "external",
    signal_type: "velocity",
    risk_score: 85,
    subject_type: "user",
    subject_id: "usr_8f14e45f",
    payload: {
      ip: "203.0.113.42",
      country: "US",
      reason: "multiple_accounts_same_device",
    },
    ip_address: "203.0.113.42",
  }),
});
const signal = await response.json();
```

```python Python theme={null}
import httpx
import uuid

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/signals",
    headers={
        "X-API-Key": "tl_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "signal_source": "external",
        "signal_type": "velocity",
        "risk_score": 85,
        "subject_type": "user",
        "subject_id": "usr_8f14e45f",
        "payload": {
            "ip": "203.0.113.42",
            "country": "US",
            "reason": "multiple_accounts_same_device",
        },
        "ip_address": "203.0.113.42",
    },
)
signal = resp.json()
```

### Champs obligatoires

| Champ | Type | Description |
| :- | :- | :- |
| `signal_source` | chaîne | Origine du signal — `verification`, `login`, `attestation`, `external`, ou `manual` |
| `signal_type` | chaîne | Ce qui a été détecté (par exemple `velocity`, `geo_anomaly`, `device_fingerprint`, `behavior`, `deepfake`, `ato`, `impersonation`) |
| `risk_score` | integer | Score de risque de `0` (sûr) à `100` (risque élevé). Les scores égaux ou supérieurs à 80 déclenchent une révision automatique. |
| `subject_type` | chaîne | Type d'entité : `user`, `issuer`, `attestation`, `session`, `ip`, ou `device` |
| `subject_id` | string | Identifiant de l'entité évaluée |

### Champs optionnels

| Champ | Type | Description |
| :- | :- | :- |
| `payload` | object | JSON arbitraire avec un contexte spécifique au signal (adresses IP, géolocalisation, raisons) |
| `ip_address` | chaîne | Adresse IP source associée à cet événement |
| `user_agent` | chaîne | Chaîne User-Agent associée à cet événement |

### Idempotence

Incluez un en-tête `Idempotency-Key` (UUID) pour éviter les signaux en double lors des tentatives. Si vous envoyez la même clé deux fois, le doublon est ignoré silencieusement.

## Interrogation des signaux

### Lister avec filtres

```bash theme={null}
curl "https://api.truthlocks.com/v1/risk/signals?source=external&min_score=50&limit=25" \
  -H "X-API-Key: tl_live_..."
```

Filtres disponibles :

| Paramètre | Description |
| :- | :- |
| `source` | Filtrer par source de signal |
| `signal_type` | Filtrer par type de signal |
| `subject_type` | Filtrer par type de sujet |
| `subject_id` | Filtrer par ID de sujet |
| `min_score` | Seuil de score minimum (0–100) |
| `limit` | Résultats par page (max 100) |
| `cursor` | Curseur pour la page suivante |

### Obtenir un seul signal

```bash theme={null}
curl https://api.truthlocks.com/v1/risk/signals/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: tl_live_..."
```

## Vue de la Console

La page **Risque et fraude > Signaux** dans la console fournit une liste consultable et filtrable de tous les signaux ingérés. Chaque ligne affiche la source, le type, le score (codé par couleur selon la gravité), la référence du sujet et l'horodatage.

Utilisez les filtres en haut de la page pour affiner les résultats par source, type de signal ou score minimum. Cliquez sur n'importe quelle ligne pour afficher tous les détails du signal, y compris l'objet de métadonnées `payload`.

## Lignes directrices de notation

Une notation cohérente entre les sources rend l'analyse en aval plus fiable. Nous recommandons les plages suivantes :

| Plage | Interprétation | Exemple |
| :- | :- | :- |
| 0 – 30 | Faible risque | Appareil connu et fiable, IP réputée |
| 30 – 60 | Risque modéré | Utilisation de VPN, vitesse de création de nouveaux comptes |
| 60 – 80 | Risque élevé | E-mail jetable, IP de centre de données |
| 80 – 100 | Risque critique | Appareil de fraude connu, voyage impossible |

> [!WARNING]
>
> Les scores égaux ou supérieurs à 80 déclenchent des décisions d'examen automatiques. L'interprétation des scores au-delà du seuil automatique vous appartient — la plateforme stocke et renvoie les scores tels quels et ne les normalise pas entre les sources.

## Normalisation des événements

Au lieu de construire manuellement des signaux de risque, vous pouvez soumettre des événements d'identité bruts et laisser la plateforme les normaliser automatiquement en signaux. Ceci est utile lorsque vous souhaitez alimenter directement le pipeline de risque avec des événements natifs de la plateforme — échecs de connexion, signatures invalides, suspects de deepfake — sans les mapper vous-même à des types de signaux.

Envoyez une requête `POST` à `/v1/risk/events` avec la source, le type et le sujet de l'événement :

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/events \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_source": "login",
    "event_type": "login.failed.repeated",
    "subject_id": "user_abc123",
    "ip_address": "198.51.100.42",
    "payload": { "attempt_count": 8, "window_seconds": 120 }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/events", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event_source: "login",
    event_type: "login.failed.repeated",
    subject_id: "user_abc123",
    ip_address: "198.51.100.42",
    payload: { attempt_count: 8, window_seconds: 120 },
  }),
});
const result = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/events",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "event_source": "login",
        "event_type": "login.failed.repeated",
        "subject_id": "user_abc123",
        "ip_address": "198.51.100.42",
        "payload": {"attempt_count": 8, "window_seconds": 120},
    },
)
result = resp.json()
```

La réponse inclut à la fois le `event_id` brut et le `signal_id` normalisé, afin que vous puissiez tracer le pipeline complet de l'événement au signal :

```json theme={null}
{
  "event_id": "2a4b6c8d-...",
  "signal_id": "9f3a1c2d-...",
  "event_type": "login.failed.repeated",
  "signal_type": "ato",
  "risk_score": 70,
  "normalized": true,
  "created_at": "2027-05-01T10:00:00Z"
}
```

Lorsque `normalized` est `true`, l'événement correspond à un mappage connu. Lorsque `false`, la plateforme a utilisé le mécanisme de secours générique.

### Mappages d'événements intégrés

La plateforme est livrée avec des mappages pré-calibrés pour les événements d'identité courants :

| Type d'événement | Type de signal | Score de base |
| :- | :- | :- |
| `verification.failed` | behavior | 60 |
| `verification.invalid_sig` | behavior | 75 |
| `login.failed.repeated` | ato | 70 |
| `login.suspicious_geo` | geo\_anomaly | 65 |
| `attestation.deepfake_suspect` | deepfake | 85 |
| `session.hijack_suspect` | ato | 90 |

Les types d'événements inconnus sont acceptés avec le type de signal `behavior` et un score de base de 10.

### Champs d'événement

**Requis :**

| Champ | Type | Description |
| :- | :- | :- |
| `event_source` | chaîne | Système ayant généré l'événement — `attestation`, `verification`, `login`, ou `consumer_portal` |
| `event_type` | chaîne | Nom de l'événement brut (par exemple `login.failed.repeated`, `attestation.deepfake_suspect`) |
| `subject_id` | string | Identifiant de l'entité impliquée dans l'événement |

**Facultatif :**

| Champ | Type | Description |
| :- | :- | :- |
| `event_ref_id` | string | ID de référence externe (ID d'attestation, ID de session) pour le référencement croisé |
| `ip_address` | chaîne | Adresse IP source |
| `payload` | object | Charge utile d'événement brute pour le contexte d'enrichissement |

> [!NOTE]
>
> Utilisez la normalisation des événements lorsque vos événements proviennent de la plateforme (connexions, vérifications, attestations). Utilisez le [point de terminaison d'ingestion de signal direct](https://docs.truthlocks.com/fr/api-reference/risk/ingest-signal.md) lorsque vous avez déjà un signal scoré provenant d'une source externe.

## Isolation du locataire

Les signaux de risque sont entièrement isolés par locataire à l'aide de la [sécurité au niveau des lignes (RLS)](https://docs.truthlocks.com/fr/security/rls.md). Chaque signal est lié au locataire authentifié au moment de l'ingestion, et les requêtes ne peuvent renvoyer que les signaux appartenant au locataire appelant.

## Détection de deepfake et d'usurpation d'identité

L'[API de détection de deepfake](https://docs.truthlocks.com/fr/guides/deepfake-detection.md) étend le pipeline de signaux de risque avec une analyse automatisée du contenu manipulé et de la fraude d'identité. Soumettez des images, des vidéos, des documents ou des attestations pour analyse, et les analyses qui dépassent le seuil de risque créent automatiquement un signal de risque — aucun appel API supplémentaire n'est nécessaire.

Consultez le [guide de détection de deepfake et d'usurpation d'identité](https://docs.truthlocks.com/fr/guides/deepfake-detection.md) pour le flux de travail complet, la référence des indicateurs et les exemples de code.

## Détection de la prise de contrôle de compte

L'[API de détection ATO](https://docs.truthlocks.com/fr/guides/ato-detection.md) étend le pipeline de signaux de risque avec une surveillance des connexions basée sur la vélocité. Envoyez les événements de connexion à `POST /v1/risk/ato/evaluate` et la plateforme suit les tentatives échouées par sujet dans une fenêtre glissante d'une heure. Lorsqu'un sujet dépasse un seuil (5, 10 ou 20 échecs de connexion), une alerte est créée et un signal de risque est automatiquement ingéré — aucun appel API supplémentaire n'est nécessaire.

Consultez le [guide de détection de prise de contrôle de compte](https://docs.truthlocks.com/fr/guides/ato-detection.md) pour le flux de travail complet, la référence des seuils et les modèles d'intégration.

## Score de vélocité et d'anomalie

L'[API de notation de vélocité](https://docs.truthlocks.com/fr/guides/velocity-scoring.md) étend le pipeline de signaux de risque avec le suivi d'actions multi-fenêtres et la détection d'anomalies. Enregistrez toute action de sujet via `POST /v1/risk/velocity/record` et la plateforme suit la fréquence sur quatre fenêtres glissantes (1 m, 5 m, 1 h, 24 h). Un score de vélocité pondéré est calculé à partir des comptes de fenêtres, biaisé vers les fenêtres courtes pour la détection de rafales. Lorsque le score atteint 60 ou plus, un signal de risque avec `signal_type: "velocity"` est automatiquement ingéré — aucun appel API supplémentaire n'est nécessaire.

Consultez le [guide de notation de vélocité et d'anomalie](https://docs.truthlocks.com/fr/guides/velocity-scoring.md) pour le flux de travail complet, le modèle de notation et les modèles d'intégration.

## Notifications de webhook

Les signaux de risque créés par l'un des cinq chemins de détection peuvent déclencher des notifications [webhook](https://docs.truthlocks.com/fr/guides/webhooks.md) en temps réel. Abonnez-vous à `risk.signal.created` ou `risk.signal.escalated` pour réagir aux nouveaux signaux sans interroger. Cela couvre les signaux provenant de l'ingestion directe, de la normalisation des événements, des analyses de deepfake, des alertes ATO et des anomalies de vélocité.

Consultez le [guide des webhooks](https://docs.truthlocks.com/fr/guides/webhooks.md#risk-signal-notifications) pour des exemples de charge utile et des modèles d'intégration.

## Mesure de l'utilisation

Les fonctionnalités anti-fraude sont mesurées par cycle de facturation. Chaque chemin de détection incrémente son propre compteur d'utilisation :

| Métrique | Action mesurée |
| :- | :- |
| `antifraud.risk_signals` | Signaux de risque ingérés ou générés (les cinq chemins) |
| `antifraud.deepfake_scans` | Demandes d'analyse de deepfake et d'usurpation d'identité |
| `antifraud.velocity_records` | Enregistrements d'action de score de vélocité |

Les quotas varient selon le niveau de votre plan. Vous pouvez vérifier votre consommation actuelle avec l'[API d'utilisation](https://docs.truthlocks.com/fr/api-reference/billing/usage.md) ou dans la console sous **Paramètres > Facturation > Utilisation** dans la section **Anti-Fraude**. Pour vérifier si une opération spécifique est autorisée avant de l'exécuter, utilisez le [point de terminaison de vérification des limites](https://docs.truthlocks.com/fr/api-reference/billing/entitlements.md).

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/usage \
  -H "X-API-Key: tl_live_..."
```

La réponse inclut tous les compteurs anti-fraude avec les champs `used`, `limit` et `period` afin que vous puissiez surveiller la consommation par programme.

> [!NOTE]
>
> Consultez l'[aperçu de la facturation](https://docs.truthlocks.com/fr/billing/overview.md#metered-products) pour la liste complète des 16 produits mesurés et leurs tarifs par défaut.

## La suite

* [Guide de la vélocité et de la notation des anomalies](https://docs.truthlocks.com/fr/guides/velocity-scoring.md)
* [Guide de détection de la prise de contrôle de compte](https://docs.truthlocks.com/fr/guides/ato-detection.md)
* [Guide de détection des deepfakes et de l'usurpation d'identité](https://docs.truthlocks.com/fr/guides/deepfake-detection.md)
* [Référence de l'API d'ingestion de signal de risque](https://docs.truthlocks.com/api-reference/risk-signals/ingest)
* [Référence de l'API de normalisation des événements d'identité](https://docs.truthlocks.com/fr/api-reference/risk/normalize-event.md)
* [Référence de l'API de liste des signaux de risque](https://docs.truthlocks.com/fr/api-reference/risk-signals/list.md)
* [Référence de l'API de signal de risque](https://docs.truthlocks.com/fr/api-reference/risk-signals/get.md)
* [Sécurité au niveau des lignes](https://docs.truthlocks.com/fr/security/rls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.