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

# Detección de toma de control de cuenta

> Detecta intentos de toma de control de cuentas con heurísticas basadas en velocidad, puntuación de riesgo automática y alertas en tiempo real.

La API de detección de toma de control de cuentas (ATO) monitorea la actividad de inicio de sesión por sujeto y marca patrones sospechosos en tiempo real. Rastrea la velocidad de inicio de sesión fallidos en una ventana móvil de una hora, asigna un nivel de riesgo basado en umbrales configurables y crea automáticamente alertas y [señales de riesgo](https://docs.truthlocks.com/es/guides/risk-signals.md) cuando se superan esos umbrales.

> [!NOTE]
>
> La detección de ATO forma parte del [Cortafuegos de Identidad Antifraude](https://docs.truthlocks.com/es/guides/risk-signals.md). Las alertas y las señales de riesgo fluyen por el mismo conducto que otras señales de fraude, por lo que puede consultarlas y revisarlas desde la página de la consola **Riesgo y Fraude > Señales** o el [endpoint de lista de señales](https://docs.truthlocks.com/es/api-reference/risk-signals/list.md).

## Cómo funciona

**1. Enviar eventos de inicio de sesión**

Llame a `POST /v1/risk/ato/evaluate` cada vez que ocurra un evento de inicio de sesión: intentos fallidos, fallas repetidas, inicios de sesión en nuevos dispositivos o inicios de sesión exitosos.

**2. Seguimiento de velocidad**

La plataforma incrementa (o restablece) el contador de inicios de sesión fallidos para el sujeto en una ventana deslizante de una hora. Los inicios de sesión exitosos restablecen la ventana.

**3. Asignación de nivel de riesgo**

Se deriva un nivel de riesgo del recuento actual de inicios de sesión fallidos. La respuesta incluye el nivel de riesgo, la puntuación numérica y el valor actual del contador.

**4. Alertas y señales automáticas**

Cuando un sujeto cruza un umbral, la plataforma crea una alerta e ingiere una señal de riesgo con `signal_type: "ato"`. No necesita una llamada a la API separada.

**5. Revisar y responder**

Consulta perfiles ATO, lista alertas y revisa señales en la consola o a través de la API para investigar y responder a amenazas.

## Requisitos previos

* Un inquilino activo de Truthlocks con una clave API
* Datos de eventos de inicio de sesión de su sistema de autenticación (inicios de sesión fallidos, éxitos, eventos de nuevos dispositivos)

## Evaluación de un evento de inicio de sesión

Envíe una solicitud `POST` a `/v1/risk/ato/evaluate` con el asunto y los detalles del evento:

```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 respuesta le indica la postura de riesgo actual y si se activó una alerta:

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

## Reglas de umbral

La plataforma asigna un nivel de riesgo basado en el número de inicios de sesión fallidos dentro de una ventana móvil de una hora:

| Inicios de sesión fallidos (ventana de 1 h) | Nivel de riesgo | Puntuación de riesgo | Tipo de alerta |
| :- | :- | :- | :- |
| 0–4 | `normal` | 10 | — |
| 5–9 | `elevated` | 50 | `velocity_exceeded` |
| 10–19 | `high` | 70 | `velocity_exceeded` |
| 20+ | `critical` | 90 | `credential_stuffing` |

Cuando se cruza un umbral:

1. Se crea una **alerta** en la tabla de alertas de ATO.
2. Se ingiere automáticamente una **señal de riesgo** con `signal_type: "ato"` y la puntuación correspondiente.
3. La respuesta incluye `alert: true`, el `alert_type` y el `signal_id`

## Tipos de eventos

| Tipo de evento | Comportamiento |
| :- | :- |
| `login.failed` | Incrementa el contador de inicios de sesión fallidos |
| `login.failed.repeated` | Incrementa el contador de inicios de sesión fallidos |
| `login.success` | Restablece el contador de inicios de sesión fallidos para el sujeto |
| `login.new_device` | Evalúa el evento y registra el nuevo dispositivo en el perfil |

## Comprobación del perfil de riesgo de un sujeto

Recuperar el perfil de riesgo ATO actual para un sujeto sin activar una nueva evaluación:

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

El perfil incluye el nivel de riesgo actual, el recuento de inicios de sesión fallidos y listas de direcciones IP y dispositivos conocidos asociados con el sujeto.

## Listado de alertas

Consultar alertas ATO para su inquilino, opcionalmente filtradas por asunto:

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

Cada alerta incluye el sujeto, el tipo de alerta, el nivel de riesgo en el momento del disparo y una referencia a la señal de riesgo auto-ingestada.

## Patrones de integración

### Bloquear o desafiar ante un riesgo elevado

Utilice el `risk_level` de la respuesta de evaluación para decidir si permitir, desafiar o bloquear un inicio de sesión:

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

### Combinar con normalización de eventos

La evaluación de ATO puede complementar la [canalización de normalización de eventos](https://docs.truthlocks.com/es/guides/risk-signals.md#event-normalization). Utilice la normalización de eventos para una puntuación de riesgo amplia en todos los eventos de identidad, y la evaluación de ATO para un monitoreo enfocado de la toma de control de cuentas con alertas basadas en umbrales.

### Combinar con puntuación de velocidad

La detección de ATO se centra en patrones de toma de control de cuentas basados en el inicio de sesión con reglas de umbral integradas y gestión de alertas. [La puntuación de velocidad](https://docs.truthlocks.com/es/guides/velocity-scoring.md) rastrea cualquier tipo de acción en múltiples ventanas de tiempo continuas (1 m, 5 m, 1 h, 24 h) con detección de ráfagas ponderada. Use ambos juntos para una protección en capas:

* **Detección de ATO** para seguridad de inicio de sesión enfocada: velocidad de inicio de sesión fallida, alertas de relleno de credenciales, perfiles de riesgo del sujeto
* **Puntuación de velocidad** para la detección general de abusos — abuso de la tasa de API, inundación de transacciones, spam de registro o cualquier tipo de acción personalizada

Ambos producen señales de riesgo en el mismo [pipeline unificado](https://docs.truthlocks.com/es/guides/risk-signals.md), para que pueda consultar y revisar todas las señales desde un solo lugar.

### Monitorear a través de webhooks

Configure un [punto final de webhook](https://docs.truthlocks.com/es/guides/webhooks.md) para recibir notificaciones en tiempo real cuando se creen alertas de ATO, para que su equipo de seguridad pueda responder sin sondeos.

## Qué sigue

* [Referencia de la API de evaluación de riesgos de ATO](https://docs.truthlocks.com/es/api-reference/risk/ato-evaluate.md)
* [Referencia de la API de obtención de perfil de ATO](https://docs.truthlocks.com/es/api-reference/risk/ato-profile.md)
* [Referencia de la API de lista de alertas de ATO](https://docs.truthlocks.com/es/api-reference/risk/ato-alerts.md)
* [Guía de señales de riesgo](https://docs.truthlocks.com/es/guides/risk-signals.md)
* [Guía de puntuación de velocidad y anomalías](https://docs.truthlocks.com/es/guides/velocity-scoring.md)
* [Guía de detección de deepfake e suplantación de identidad](https://docs.truthlocks.com/es/guides/deepfake-detection.md)


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