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

# Detecção de aquisição de conta

> Detecta tentativas de tomada de conta com heurísticas baseadas em velocidade, pontuação de risco automática e alertas em tempo real.

A API de detecção de tomada de conta (ATO) monitora a atividade de login por assunto e sinaliza padrões suspeitos em tempo real. Ela rastreia a velocidade de logins falhos em uma janela contínua de uma hora, atribui um nível de risco com base em limites configuráveis e cria automaticamente alertas e [sinais de risco](https://docs.truthlocks.com/pt/guides/risk-signals.md) quando esses limites são excedidos.

> [!NOTE]
>
> A detecção de ATO faz parte do [Anti-Fraud Identity Firewall](https://docs.truthlocks.com/pt/guides/risk-signals.md). Alertas e sinais de risco fluem para o mesmo pipeline que outros sinais de fraude, para que você possa consultá-los e revisá-los na página do console **Risco e Fraude > Sinais** ou no [endpoint de listagem de sinais](https://docs.truthlocks.com/pt/api-reference/risk-signals/list.md).

## Como funciona

**1. Enviar eventos de login**

Chame `POST /v1/risk/ato/evaluate` cada vez que um evento de login ocorrer — tentativas falhas, falhas repetidas, logins de novos dispositivos ou logins bem-sucedidos.

**2. Rastreamento de velocidade**

A plataforma incrementa (ou redefine) o contador de logins falhos para o assunto em uma janela contínua de uma hora. Logins bem-sucedidos redefinem a janela.

**3. Atribuição de nível de risco**

Um nível de risco é derivado da contagem atual de logins falhos. A resposta inclui o nível de risco, a pontuação numérica e o valor atual do contador.

**4. Alertas e sinais automáticos**

Quando um assunto cruza um limite, a plataforma cria um alerta e ingere um sinal de risco com `signal_type: "ato"`. Você não precisa de uma chamada de API separada.

**5. Revisar e responder**

Consulte perfis ATO, liste alertas e revise sinais na console ou via API para investigar e responder a ameaças.

## Pré-requisitos

* Um inquilino Truthlocks ativo com uma chave de API
* Dados de eventos de login do seu sistema de autenticação (logins falhos, sucessos, novos eventos de dispositivo)

## Avaliando um evento de login

Envie uma requisição `POST` para `/v1/risk/ato/evaluate` com o assunto e detalhes do 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()
```

A resposta informa a postura de risco atual e se um alerta foi acionado:

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

## Regras de limite

A plataforma atribui um nível de risco com base no número de logins falhos em uma janela deslizante de uma hora:

| Logins falhos (janela de 1 h) | Nível de risco | Pontuação de risco | Tipo de alerta |
| :- | :- | :- | :- |
| 0–4 | `normal` | 10 | — |
| 5–9 | `elevated` | 50 | `velocity_exceeded` |
| 10–19 | `high` | 70 | `velocity_exceeded` |
| 20+ | `critical` | 90 | `credential_stuffing` |

Quando um limite é ultrapassado:

1. Um **alerta** é criado na tabela de alertas ATO
2. Um **sinal de risco** é automaticamente ingerido com `signal_type: "ato"` e a pontuação correspondente
3. A resposta inclui `alert: true`, o `alert_type` e o `signal_id`

## Tipos de eventos

| Tipo de evento | Comportamento |
| :- | :- |
| `login.failed` | Incrementa o contador de logins falhos |
| `login.failed.repeated` | Incrementa o contador de logins falhos |
| `login.success` | Redefine o contador de login falho para o assunto |
| `login.new_device` | Avalia o evento e regista o novo dispositivo no perfil |

## Verificando o perfil de risco de um sujeito

Recupere o perfil de risco ATO atual para um assunto sem acionar uma nova avaliação:

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

O perfil inclui o nível de risco atual, a contagem de logins falhos e listas de endereços IP e dispositivos conhecidos associados ao sujeito.

## Listando alertas

Consulte os alertas ATO para seu locatário, opcionalmente filtrados por assunto:

```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 inclui o assunto, tipo de alerta, nível de risco no momento do disparo e uma referência ao sinal de risco auto-ingerido.

## Padrões de integração

### Bloquear ou desafiar em caso de risco elevado

Use o `risk_level` da resposta de avaliação para decidir se permite, desafia ou bloqueia um login:

```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 com normalização de eventos

A avaliação de ATO pode complementar o [pipeline de normalização de eventos](https://docs.truthlocks.com/pt/guides/risk-signals.md#event-normalization). Use a normalização de eventos para pontuação de risco ampla em todos os eventos de identidade e a avaliação de ATO para monitoramento focado de aquisição de conta com alertas baseados em limite.

### Combinar com pontuação de velocidade

A detecção de ATO se concentra em padrões de aquisição de conta baseados em login com regras de limite integradas e gerenciamento de alertas. [A pontuação de velocidade](https://docs.truthlocks.com/pt/guides/velocity-scoring.md) rastreia qualquer tipo de ação em várias janelas de tempo contínuas (1 m, 5 m, 1 h, 24 h) com detecção de pico ponderada. Use ambos juntos para proteção em camadas:

* **Detecção de ATO** para segurança de login focada — velocidade de login falho, alertas de preenchimento de credenciais, perfis de risco do sujeito
* **Pontuação de velocidade** para detecção geral de abuso — abuso de taxa de API, inundação de transações, spam de registro ou qualquer tipo de ação personalizada

Ambos produzem sinais de risco no mesmo [pipeline unificado](https://docs.truthlocks.com/pt/guides/risk-signals.md), para que você possa consultar e revisar todos os sinais de um só lugar.

### Monitorizar via webhooks

Configure um [endpoint de webhook](https://docs.truthlocks.com/pt/guides/webhooks.md) para receber notificações em tempo real quando alertas ATO forem criados, para que sua equipe de segurança possa responder sem sondagem.

## O que vem a seguir

* [Avaliar referência da API de risco ATO](https://docs.truthlocks.com/pt/api-reference/risk/ato-evaluate.md)
* [Obter referência da API de perfil ATO](https://docs.truthlocks.com/pt/api-reference/risk/ato-profile.md)
* [Listar referência da API de alertas ATO](https://docs.truthlocks.com/pt/api-reference/risk/ato-alerts.md)
* [Guia de sinais de risco](https://docs.truthlocks.com/pt/guides/risk-signals.md)
* [Guia de pontuação de velocidade e anomalias](https://docs.truthlocks.com/pt/guides/velocity-scoring.md)
* [Guia de detecção de deepfake e personificação](https://docs.truthlocks.com/pt/guides/deepfake-detection.md)


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