Skip to main content
POST
/
v1
/
risk
/
ato
/
evaluate
ATO risk evaluate
curl --request POST \
  --url https://api.truthlocks.com/v1/risk/ato/evaluate \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "subject_id": "<string>",
  "ip_address": "<string>",
  "user_agent": "<string>",
  "device_fingerprint": "<string>",
  "action": "<string>"
}
'
{
  "risk_score": 123,
  "decision": "<string>",
  "signals": [
    {}
  ]
}
Evaluates a login event against the ATO heuristic engine. The platform tracks failed logins per subject in a rolling one-hour window and derives a risk level from the current count. When a threshold is crossed, an alert is created and a risk signal is automatically ingested into the risk signal pipeline. See the account takeover detection guide for the full workflow, threshold reference, and integration patterns.

​
Threshold rules

Failed logins (1 h window)Risk levelAuto-alert
0–4normalNo
5–9elevatedYes — velocity_exceeded
10–19highYes — velocity_exceeded
20+criticalYes — credential_stuffing

​
Request

​
subject_id
string
required
User identifier (user ID, email, or external ID).
​
event_type
string
required
Login event type: login.failed, login.failed.repeated, login.success, login.new_device
​
subject_type
string
Type of subject. Defaults to user.
​
ip_address
string
Source IP address for the login attempt.

​
Response

​
subject_id
string
The subject that was evaluated.
​
subject_type
string
Type of subject (user).
​
risk_level
string
Current ATO risk level: normal | elevated | high | critical
​
risk_score
integer
Numeric risk score: 10 (normal), 50 (elevated), 70 (high), 90 (critical).
​
failed_login_count
integer
Number of failed logins in the current one-hour window.
​
alert
boolean
true if a new alert was triggered by this evaluation.
​
alert_type
string
Alert category when triggered: velocity_exceeded or credential_stuffing.
​
signal_id
string
UUID of the auto-ingested risk signal (only present when an alert fired).
​
event_type
string
The event type that was evaluated.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
subject_id
string
required
​
ip_address
string
​
user_agent
string
​
device_fingerprint
string
​
action
string

Response

ATO evaluation result

​
risk_score
integer
​
decision
string
​
signals
object[]