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

# Notation de vélocité et d'anomalie

> Suivez la fréquence des actions sur des fenêtres temporelles glissantes, détectez les anomalies de vélocité et ingérez automatiquement les signaux de risque lorsque les seuils sont dépassés.

L'API de score de vélocité et d'anomalie suit la fréquence à laquelle un sujet effectue une action donnée sur plusieurs fenêtres temporelles glissantes — 1 minute, 5 minutes, 1 heure et 24 heures. Lorsque le score de vélocité pondéré dépasse un seuil, la plateforme crée automatiquement un [signal de risque](https://docs.truthlocks.com/fr/guides/risk-signals.md), connectant la détection d'anomalie directement au pipeline du pare-feu d'identité anti-fraude.

> [!NOTE]
>
> La notation de vélocité fait partie du [pare-feu d'identité anti-fraude](https://docs.truthlocks.com/fr/guides/risk-signals.md). Les signaux générés par les anomalies de vélocité s'intègrent au même pipeline que les autres signaux de fraude, vous pouvez donc les interroger et les examiner depuis la page de la console **Risque & Fraude > Signaux** ou le [point de terminaison de liste des signaux](https://docs.truthlocks.com/fr/api-reference/risk-signals/list.md).

## Comment ça marche

**1. Enregistrer les actions**

Appelez `POST /v1/risk/velocity/record` chaque fois qu'un sujet effectue une action suivie — tentatives de connexion, appels API, demandes de transaction ou tout type d'action personnalisée.

**2. Suivi par fenêtre glissante**

La plateforme incrémente les compteurs pour le sujet et le type d'action sur quatre fenêtres glissantes (1 m, 5 m, 1 h, 24 h). Les fenêtres se réinitialisent automatiquement à leur expiration.

**3. Notation pondérée**

Un score de vélocité est calculé à partir des comptes de fenêtre. Les fenêtres courtes sont pondérées plus lourdement pour détecter les rafales : 1 m × 30, 5 m × 20, 1 h × 10, 24 h × 5.

**4. Ingestion automatique de signaux**

Lorsque le score de vélocité atteint 60 ou plus, la plateforme ingère automatiquement un signal de risque avec `signal_type: "velocity"`. Vous n'avez pas besoin d'un appel API séparé.

**5. Examiner et répondre**

Interrogez les fenêtres de vélocité pour un sujet, listez les anomalies à haute vélocité dans votre locataire, et examinez les signaux dans la console ou via l'API.

## Prérequis

* Un locataire Truthlocks actif avec une clé API
* Données d'événements d'action de votre application (tentatives de connexion, appels API, transactions ou toute action reproductible)

## Enregistrement d'une action

Envoyez une requête `POST` à `/v1/risk/velocity/record` avec le sujet, le type d'action et les métadonnées facultatives :

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/velocity/record \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user_abc123",
    "action_type": "login.failed",
    "ip_address": "198.51.100.42"
  }'
```

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

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

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/velocity/record",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "subject_id": "user_abc123",
        "action_type": "login.failed",
        "ip_address": "198.51.100.42",
    },
)
result = resp.json()
```

La réponse renvoie le nombre de fenêtres actuelles, le score de vélocité calculé et si un signal de risque a été automatiquement ingéré :

```json theme={null}
{
  "subject_id": "user_abc123",
  "action_type": "login.failed",
  "windows": {
    "1m": 3,
    "5m": 8,
    "1h": 15,
    "24h": 42
  },
  "velocity_score": 72,
  "signal_ingested": true,
  "signal_id": "a1b2c3d4-..."
}
```

## Modèle de notation

Le score de vélocité est une somme pondérée des nombres d'actions sur quatre fenêtres glissantes. Les fenêtres courtes ont un poids plus élevé pour prioriser la détection des pics:

| Fenêtre | Poids | Objectif |
| :- | :- | :- |
| 1 minute | 30 | Détecte les rafales rapides (bourrage d'identifiants, attaques automatisées) |
| 5 minutes | 20 | Détecte les abus soutenus à court terme |
| 1 heure | 10 | Identifie les modèles à moyen terme |
| 24 heures | 5 | Signale les anomalies persistantes sur de plus longues périodes |

Le score final est plafonné à 100. Lorsque le score atteint **60 ou plus**, un signal de risque est automatiquement ingéré avec `signal_type: "velocity"`.

### Interprétation du score

| Plage de scores | Interprétation | Exemple |
| :- | :- | :- |
| 0–29 | Normal | Activité utilisateur typique |
| 30–59 | Élevé | Fréquence supérieure à la moyenne, à surveiller |
| 60–79 | Élevé | Probablement automatisé ou abusif — signal auto-ingéré |
| 80–100 | Critique | Forte anomalie — enquête immédiate recommandée |

## Interrogation des fenêtres de vélocité

Récupère les fenêtres de vélocité actuelles pour un sujet spécifique :

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

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/velocity/user_abc123", {
  headers: { "X-API-Key": "tl_live_..." },
});
const windows = await response.json();
```

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

resp = httpx.get(
    "https://api.truthlocks.com/v1/risk/velocity/user_abc123",
    headers={"X-API-Key": "tl_live_..."},
)
windows = resp.json()
```

La réponse inclut tous les types d'actions suivis pour le sujet, avec des comptes par fenêtre et le score de vélocité calculé pour chacun :

```json theme={null}
{
  "subject_id": "user_abc123",
  "actions": [
    {
      "action_type": "login.failed",
      "windows": {
        "1m": 0,
        "5m": 2,
        "1h": 8,
        "24h": 23
      },
      "velocity_score": 45
    },
    {
      "action_type": "api.request",
      "windows": {
        "1m": 12,
        "5m": 45,
        "1h": 200,
        "24h": 800
      },
      "velocity_score": 87
    }
  ]
}
```

## Liste des anomalies à haute vélocité

Interroger les sujets avec des scores de vélocité supérieurs à un seuil dans votre locataire :

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

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.truthlocks.com/v1/risk/velocity?min_score=50&limit=25",
  { headers: { "X-API-Key": "tl_live_..." } }
);
const anomalies = await response.json();
```

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

resp = httpx.get(
    "https://api.truthlocks.com/v1/risk/velocity",
    params={"min_score": 50, "limit": 25},
    headers={"X-API-Key": "tl_live_..."},
)
anomalies = resp.json()
```

Chaque résultat inclut le sujet, le type d'action, les comptes de fenêtre actuels et le score de vélocité qui a qualifié l'anomalie :

```json theme={null}
{
  "anomalies": [
    {
      "subject_id": "user_abc123",
      "action_type": "login.failed",
      "windows": {
        "1m": 5,
        "5m": 12,
        "1h": 30,
        "24h": 85
      },
      "velocity_score": 68,
      "last_recorded_at": "2027-07-03T14:22:00Z"
    }
  ],
  "cursor": "eyJsYXN0X2lkIjo..."
}
```

## Modèles d'intégration

### Bloquer ou limiter en cas de vélocité élevée

Utilisez le score de vélocité de la réponse d'enregistrement pour décider d'autoriser, de limiter ou de bloquer une action :

```javascript theme={null}
const result = await recordAction(subjectId, "api.request", ipAddress);

if (result.velocity_score >= 80) {
  await blockSubject(subjectId);
  await notifySecurityTeam(result);
} else if (result.velocity_score >= 60) {
  await throttleRequests(subjectId, { maxPerMinute: 5 });
} else if (result.velocity_score >= 30) {
  await addRateLimitWarning(subjectId);
}
```

### Combiner avec la détection ATO

La notation de vélocité suit tout type d'action sur plusieurs fenêtres temporelles, tandis que la [détection ATO](https://docs.truthlocks.com/fr/guides/ato-detection.md) est spécifiquement optimisée pour les modèles de prise de contrôle de compte basés sur la connexion avec des règles de seuil et une gestion des alertes intégrées. Utilisez les deux ensemble pour une protection multicouche :

* **Notation de vélocité** pour la détection générale des abus — abus de taux d'API, inondation de transactions, spam d'inscription
* **Détection ATO** pour une sécurité de connexion ciblée — vitesse de connexion échouée, alertes de bourrage d'identifiants, profils de risque du sujet

### Surveiller via des webhooks

Configurez un [point de terminaison de webhook](https://docs.truthlocks.com/fr/guides/webhooks.md) pour recevoir des notifications en temps réel lorsque des signaux de risque basés sur la vélocité sont créés, afin que votre équipe de sécurité puisse réagir sans interroger.

### Types d'actions personnalisées

Vous pouvez suivre tout type d'action produit par votre application. Exemples courants :

| Type d'action | Cas d'utilisation |
| :- | :- |
| `login.failed` | Tentatives de connexion échouées |
| `api.request` | Fréquence des appels API |
| `transaction.create` | Tentatives de paiement ou de transfert |
| `registration.attempt` | Spam de création de compte |
| `password.reset` | Abus de réinitialisation de mot de passe |
| `verification.request` | Inondation de requêtes de vérification |

## Mesure de l'utilisation

Chaque appel à `POST /v1/risk/velocity/record` incrémente le compteur d'utilisation `antifraud.velocity_records` pour votre cycle de facturation. Vous pouvez surveiller votre consommation 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**.

> [!NOTE]
>
> Les quotas d'enregistrements de vélocité varient selon le niveau de plan. Consultez l'[aperçu de la facturation](https://docs.truthlocks.com/fr/billing/overview.md#metered-products) pour plus de détails sur tous les produits mesurés Anti-Fraude.

## La suite

* [Référence de l'API d'action de vélocité d'enregistrement](https://docs.truthlocks.com/fr/api-reference/risk/velocity-record.md)
* [Référence de l'API des fenêtres de vélocité](https://docs.truthlocks.com/fr/api-reference/risk/velocity-windows.md)
* [Référence de l'API de liste des anomalies de vélocité](https://docs.truthlocks.com/fr/api-reference/risk/velocity-anomalies.md)
* [Guide des signaux de risque](https://docs.truthlocks.com/fr/guides/risk-signals.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)


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