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

# Erkennung von Kontoübernahmen

> Erkennen Sie Versuche zur Kontoübernahme mit geschwindigkeitsbasierten Heuristiken, automatischer Risikobewertung und Echtzeitwarnungen.

Die API zur Erkennung von Kontoübernahmen (ATO) überwacht die Anmeldeaktivität pro Subjekt und kennzeichnet verdächtige Muster in Echtzeit. Sie verfolgt die Geschwindigkeit fehlgeschlagener Anmeldungen in einem rollierenden einstündigen Fenster, weist ein Risikoniveau basierend auf konfigurierbaren Schwellenwerten zu und erstellt automatisch Warnungen und [Risikosignale](https://docs.truthlocks.com/de/guides/risk-signals.md), wenn diese Schwellenwerte überschritten werden.

> [!NOTE]
>
> Die ATO-Erkennung ist Teil der [Anti-Fraud Identity Firewall](https://docs.truthlocks.com/de/guides/risk-signals.md). Warnungen und Risikosignale fließen in dieselbe Pipeline wie andere Betrugssignale, sodass Sie diese auf der Konsolenseite **Risk & Fraud > Signals** oder über den [list signals endpoint](https://docs.truthlocks.com/de/api-reference/risk-signals/list.md) abfragen und überprüfen können.

## Funktionsweise

**1. Login-Ereignisse senden**

Rufen Sie `POST /v1/risk/ato/evaluate` jedes Mal auf, wenn ein Anmeldeereignis auftritt – fehlgeschlagene Versuche, wiederholte Fehler, Anmeldungen von neuen Geräten oder erfolgreiche Anmeldungen.

**2. Geschwindigkeitsverfolgung**

Die Plattform erhöht (oder setzt zurück) den Zähler für fehlgeschlagene Anmeldungen für das Subjekt in einem rollierenden einstündigen Fenster. Erfolgreiche Anmeldungen setzen das Fenster zurück.

**3. Zuordnung des Risikolevels**

Ein Risikolevel wird aus der aktuellen Anzahl fehlgeschlagener Anmeldungen abgeleitet. Die Antwort enthält das Risikolevel, den numerischen Wert und den aktuellen Zählerwert.

**4. Automatische Alarme und Signale**

Wenn ein Subjekt einen Schwellenwert überschreitet, erstellt die Plattform einen Alarm und nimmt ein Risikosignal mit `signal_type: "ato"` auf. Sie benötigen keinen separaten API-Aufruf.

**5. Überprüfen und antworten**

Fragen Sie ATO-Profile ab, listen Sie Warnungen auf und überprüfen Sie Signale in der Konsole oder über die API, um Bedrohungen zu untersuchen und darauf zu reagieren.

## Voraussetzungen

* Ein aktiver Truthlocks-Mandant mit einem API-Schlüssel
* Anmeldeereignisdaten aus Ihrem Authentifizierungssystem (fehlgeschlagene Anmeldungen, Erfolge, neue Geräteereignisse)

## Ein Anmeldeereignis bewerten

Senden Sie eine `POST`-Anfrage an `/v1/risk/ato/evaluate` mit dem Betreff und den Ereignisdetails:

```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()
```

Die Antwort teilt Ihnen die aktuelle Risikoposition mit und ob ein Alarm ausgelöst wurde:

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

## Schwellenwertregeln

Die Plattform weist ein Risikoniveau basierend auf der Anzahl fehlgeschlagener Anmeldungen innerhalb eines rollierenden Ein-Stunden-Fensters zu:

| Fehlgeschlagene Anmeldungen (1-Stunden-Fenster) | Risikostufe | Risikobewertung | Alarmtyp |
| :- | :- | :- | :- |
| 0–4 | `normal` | 10 | — |
| 5–9 | `elevated` | 50 | `velocity_exceeded` |
| 10–19 | `high` | 70 | `velocity_exceeded` |
| 20+ | `critical` | 90 | `credential_stuffing` |

Wenn ein Schwellenwert überschritten wird:

1. Eine **Warnung** wird in der ATO-Warnungstabelle erstellt
2. Ein **Risikosignal** wird automatisch mit `signal_type: "ato"` und dem entsprechenden Score erfasst
3. Die Antwort enthält `alert: true`, die `alert_type` und die `signal_id`

## Ereignistypen

| Ereignistyp | Verhalten |
| :- | :- |
| `login.failed` | Erhöht den Zähler für fehlgeschlagene Anmeldungen |
| `login.failed.repeated` | Erhöht den Zähler für fehlgeschlagene Anmeldungen |
| `login.success` | Setzt den Zähler für fehlgeschlagene Anmeldungen für das Subjekt zurück |
| `login.new_device` | Bewertet das Ereignis und zeichnet das neue Gerät im Profil auf |

## Risikoprofil eines Subjekts prüfen

Rufen Sie das aktuelle ATO-Risikoprofil für ein Subjekt ab, ohne eine neue Bewertung auszulösen:

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

Das Profil enthält das aktuelle Risikoniveau, die Anzahl fehlgeschlagener Anmeldungen und Listen bekannter IP-Adressen und Geräte, die dem Subjekt zugeordnet sind.

## Warnmeldungen auflisten

ATO-Warnungen für Ihren Mandanten abfragen, optional nach Betreff gefiltert:

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

Jede Warnung enthält das Subjekt, den Warnungstyp, das Risikoniveau zum Zeitpunkt der Auslösung und einen Verweis auf das automatisch erfasste Risikosignal.

## Integrationsmuster

### Blockieren oder Anfechten bei erhöhtem Risiko

Verwenden Sie den `risk_level` aus der Auswertungsantwort, um zu entscheiden, ob ein Login zugelassen, angefochten oder blockiert werden soll:

```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);
}
```

### Mit Ereignisnormalisierung kombinieren

Die ATO-Bewertung kann die [Ereignisnormalisierungspipeline](https://docs.truthlocks.com/de/guides/risk-signals.md#event-normalization) ergänzen. Verwenden Sie die Ereignisnormalisierung für eine breite Risikobewertung über alle Identitätsereignisse hinweg und die ATO-Bewertung für eine fokussierte Kontoüberwachungsüberwachung mit schwellenwertbasierten Warnungen.

### Mit Geschwindigkeitsbewertung kombinieren

Die ATO-Erkennung konzentriert sich auf loginbasierte Kontoübernahmemuster mit integrierten Schwellenwertregeln und Warnungsverwaltung. [Velocity Scoring](https://docs.truthlocks.com/de/guides/velocity-scoring.md) verfolgt jeden Aktionstyp über mehrere rollierende Zeitfenster (1 m, 5 m, 1 h, 24 h) mit gewichteter Burst-Erkennung. Verwenden Sie beides zusammen für einen mehrschichtigen Schutz:

* **ATO-Erkennung** für fokussierte Anmeldesicherheit – Geschwindigkeit fehlgeschlagener Anmeldungen, Warnungen bei Credential Stuffing, Risikoprofile von Subjekten
* **Geschwindigkeitsbewertung** zur allgemeinen Missbrauchserkennung – API-Ratenmissbrauch, Transaktionsflut, Registrierungs-Spam oder jede benutzerdefinierte Aktionstyp

Beide erzeugen Risikosignale in derselben [einheitlichen Pipeline](https://docs.truthlocks.com/de/guides/risk-signals.md), sodass Sie alle Signale von einem Ort aus abfragen und überprüfen können.

### Über Webhooks überwachen

Konfigurieren Sie einen [Webhook-Endpunkt](https://docs.truthlocks.com/de/guides/webhooks.md), um Echtzeitbenachrichtigungen zu erhalten, wenn ATO-Warnungen erstellt werden, damit Ihr Sicherheitsteam ohne Abfragen reagieren kann.

## Was als Nächstes kommt

* [API-Referenz zur Bewertung des ATO-Risikos](https://docs.truthlocks.com/de/api-reference/risk/ato-evaluate.md)
* [API-Referenz zum Abrufen des ATO-Profils](https://docs.truthlocks.com/de/api-reference/risk/ato-profile.md)
* [API-Referenz zum Auflisten von ATO-Warnungen](https://docs.truthlocks.com/de/api-reference/risk/ato-alerts.md)
* [Leitfaden für Risikosignale](https://docs.truthlocks.com/de/guides/risk-signals.md)
* [Leitfaden zur Geschwindigkeits- und Anomaliebewertung](https://docs.truthlocks.com/de/guides/velocity-scoring.md)
* [Leitfaden zur Erkennung von Deepfakes und Identitätsdiebstahl](https://docs.truthlocks.com/de/guides/deepfake-detection.md)


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