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

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

> Détectez les tentatives de prise de contrôle de compte avec des heuristiques basées sur la vélocité, une notation automatique des risques et des alertes en temps réel.

L'API de détection de prise de contrôle de compte (ATO) surveille l'activité de connexion par sujet et signale les schémas suspects en temps réel. Elle suit la vitesse des échecs de connexion sur une fenêtre glissante d'une heure, attribue un niveau de risque basé sur des seuils configurables et crée automatiquement des alertes et des [signaux de risque](https://docs.truthlocks.com/fr/guides/risk-signals.md) lorsque ces seuils sont dépassés.

> [!NOTE]
>
> La détection ATO fait partie du [pare-feu d'identité anti-fraude](https://docs.truthlocks.com/fr/guides/risk-signals.md). Les alertes et les signaux de risque sont acheminés dans le même pipeline que les autres signaux de fraude, vous pouvez donc les interroger et les examiner depuis la page de la console **Risque et 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. Envoyer les événements de connexion**

Appelez `POST /v1/risk/ato/evaluate` chaque fois qu'un événement de connexion se produit — tentatives échouées, échecs répétés, connexions depuis un nouvel appareil ou connexions réussies.

**2. Suivi de la vélocité**

La plateforme incrémente (ou réinitialise) le compteur de tentatives de connexion échouées pour le sujet dans une fenêtre glissante d'une heure. Les connexions réussies réinitialisent la fenêtre.

**3. Attribution du niveau de risque**

Un niveau de risque est dérivé du nombre actuel d'échecs de connexion. La réponse inclut le niveau de risque, le score numérique et la valeur actuelle du compteur.

**4. Alertes et signaux automatiques**

Lorsqu'un sujet dépasse un seuil, la plateforme crée une alerte et ingère un signal de risque avec `signal_type: "ato"`. Vous n'avez pas besoin d'un appel API séparé.

**5. Examiner et répondre**

Interrogez les profils ATO, listez les alertes et examinez les signaux dans la console ou via l'API pour enquêter et répondre aux menaces.

## Prérequis

* Un locataire Truthlocks actif avec une clé API
* Données d'événements de connexion de votre système d'authentification (connexions échouées, réussites, nouveaux événements d'appareil)

## Évaluation d'un événement de connexion

Envoyez une requête `POST` à `/v1/risk/ato/evaluate` avec le sujet et les détails de l'événement :

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

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/ato/evaluate", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subject_id: "user_abc123",
    event_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/ato/evaluate",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "subject_id": "user_abc123",
        "event_type": "login.failed",
        "ip_address": "198.51.100.42",
    },
)
result = resp.json()
```

La réponse vous indique la posture de risque actuelle et si une alerte a été déclenchée :

```json theme={null}
{
  "subject_id": "user_abc123",
  "subject_type": "user",
  "risk_level": "elevated",
  "risk_score": 50,
  "failed_login_count": 5,
  "alert": true,
  "alert_type": "velocity_exceeded",
  "signal_id": "9f3a1c2d-...",
  "event_type": "login.failed"
}
```

## Règles de seuil

La plateforme attribue un niveau de risque basé sur le nombre d'échecs de connexion dans une fenêtre glissante d'une heure :

| Connexions échouées (fenêtre d'1 h) | Niveau de risque | Score de risque | Type d'alerte |
| :- | :- | :- | :- |
| 0–4 | `normal` | 10 | — |
| 5–9 | `elevated` | 50 | `velocity_exceeded` |
| 10–19 | `high` | 70 | `velocity_exceeded` |
| 20+ | `critical` | 90 | `credential_stuffing` |

Lorsqu'un seuil est dépassé :

1. Une **alerte** est créée dans le tableau des alertes ATO
2. Un **signal de risque** est automatiquement ingéré avec `signal_type: "ato"` et le score correspondant
3. La réponse inclut `alert: true`, le `alert_type`, et le `signal_id`

## Types d'événements

| Type d'événement | Comportement |
| :- | :- |
| `login.failed` | Incrémente le compteur de tentatives de connexion échouées |
| `login.failed.repeated` | Incrémente le compteur de tentatives de connexion échouées |
| `login.success` | Réinitialise le compteur de tentatives de connexion échouées pour le sujet |
| `login.new_device` | Évalue l'événement et enregistre le nouvel appareil dans le profil |

## Vérification du profil de risque d'un sujet

Récupère le profil de risque ATO actuel pour un sujet sans déclencher une nouvelle évaluation :

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

Le profil comprend le niveau de risque actuel, le nombre d'échecs de connexion et les listes d'adresses IP et d'appareils connus associés au sujet.

## Liste des alertes

Interroger les alertes ATO pour votre locataire, éventuellement filtrées par sujet :

```bash theme={null}
curl "https://api.truthlocks.com/v1/risk/ato/alerts?subject_id=user_abc123&limit=10" \
  -H "X-API-Key: tl_live_..."
```

Chaque alerte comprend le sujet, le type d'alerte, le niveau de risque au moment du déclenchement et une référence au signal de risque auto-ingéré.

## Modèles d'intégration

### Bloquer ou contester en cas de risque élevé

Utilisez le `risk_level` de la réponse d'évaluation pour décider d'autoriser, de contester ou de bloquer une connexion :

```javascript theme={null}
const result = await evaluateATO(subjectId, "login.failed", ipAddress);

if (result.risk_level === "critical") {
  await lockAccount(subjectId);
  await notifySecurityTeam(result);
} else if (result.risk_level === "high") {
  await requireMFA(subjectId);
} else if (result.risk_level === "elevated") {
  await addCaptchaChallenge(subjectId);
}
```

### Combiner avec la normalisation des événements

L'évaluation ATO peut compléter le [pipeline de normalisation des événements](https://docs.truthlocks.com/fr/guides/risk-signals.md#event-normalization). Utilisez la normalisation des événements pour une évaluation large des risques sur tous les événements d'identité, et l'évaluation ATO pour une surveillance ciblée de la prise de contrôle de compte avec des alertes basées sur des seuils.

### Combiner avec la notation de vélocité

La détection ATO se concentre sur les modèles de prise de contrôle de compte basés sur la connexion avec des règles de seuil intégrées et la gestion des alertes. [Le score de vélocité](https://docs.truthlocks.com/fr/guides/velocity-scoring.md) suit tout type d'action sur plusieurs fenêtres de temps glissantes (1 m, 5 m, 1 h, 24 h) avec détection de rafale pondérée. Utilisez les deux ensemble pour une protection multicouche :

* **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
* **Notation de vélocité** pour la détection générale des abus — abus de taux d'API, inondation de transactions, spam d'inscription ou tout type d'action personnalisée

Les deux produisent des signaux de risque dans le même [pipeline unifié](https://docs.truthlocks.com/fr/guides/risk-signals.md), vous pouvez donc interroger et examiner tous les signaux à partir d'un seul endroit.

### 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 alertes ATO sont créées, afin que votre équipe de sécurité puisse réagir sans interroger.

## La suite

* [Référence de l'API d'évaluation des risques ATO](https://docs.truthlocks.com/fr/api-reference/risk/ato-evaluate.md)
* [Référence de l'API de profil ATO](https://docs.truthlocks.com/fr/api-reference/risk/ato-profile.md)
* [Référence de l'API de liste des alertes ATO](https://docs.truthlocks.com/fr/api-reference/risk/ato-alerts.md)
* [Guide des signaux de risque](https://docs.truthlocks.com/fr/guides/risk-signals.md)
* [Guide de la vélocité et de la notation des anomalies](https://docs.truthlocks.com/fr/guides/velocity-scoring.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.