Bearer Token Authentication

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer sk_test_YOUR_API_KEY

Test vs Live Keys

Request Parameters

Response Parameters

Try It Out

How it works

1. The usual checks run first (email, IP, VPN, blocklists) and produce the base risk_score.
2. The call is stored as an event: type, email pattern, IP, /24 subnet, country and your user_id. Test keys write test-mode events that never mix with live history.
3. Velocity counts are taken over your account's events, including this one, so ip_signups_1h: 3 means this call is the third.
4. Each rule below is checked. A rule that fires adds its weight to the score (capped at 100), may raise the recommendation floor, and adds its code to data.checks and to the end of message.

Events

signup, login, checkout, password_reset, check, or your own custom:<name> (lowercase letters, digits and underscores, up to 24 characters). The burst rules only count signup events; the shared-IP rule only looks at non-signup events; the travel rules need a user_id.

Anomaly codes

Example

The third signup from the same IP inside an hour:

curl -X POST https://fidro.io/api/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "c@example.com", "ip": "1.1.1.1", "event": "signup", "user_id": "usr_3"}'

{
  "test_mode": true,
  "risk_score": 40,
  "recommendation": "challenge",
  "message": "No risk factors detected. Velocity: ip signup burst.",
  "data": {
    "checks": { "disposable_email": false, "vpn": false, "ip_signup_burst": true },
    "location": { "country_code": "US" },
    "velocity": {
      "ip_events_1h": 3, "ip_events_24h": 3,
      "ip_signups_1h": 3, "ip_signups_24h": 3,
      "subnet_signups_1h": 3, "ip_distinct_users_24h": 1,
      "email_pattern_matches_24h": 1,
      "user_distinct_ips_24h": 1, "user_countries_30d": 1
    },
    "anomalies": [
      {
        "code": "ip_signup_burst",
        "severity": "high",
        "detail": "3 signups from 1.1.1.1 in the last hour."
      }
    ]
  },
  "request_id": "req_...",
  "timestamp": "2026-10-02T10:00:00.000000Z"
}

Good to know

• Velocity is counted on every stateful call, even when the email and IP result came from the 24-hour response cache. A second signup from the same address still moves the counts.
• Test keys have their own history. Three signup calls from the same IP with a test key reproduce ip_signup_burst on demand. In test mode the country_code you send stands in for the IP's country, so changing it between two calls for the same user_id reproduces impossible_travel.
• Events are kept for 7 days on Free, 90 days on Starter and 365 days on Pro and Enterprise. Older events are deleted nightly.
• Each event is one request against your monthly quota, the same as a stateless check.
• Events and anomalies appear in the dashboard audit log alongside the request.

Current Limits

Response Headers

Every API response includes rate limit information in the response headers. Use these headers to track your usage and implement appropriate backoff strategies.

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1762784176

Rate Limit Exceeded

When you exceed the rate limit, the API will return a 429 Too Many Requests status code with details about when you can retry.

{
  "message": "Too Many Requests",
  "retry_after": 42
}

How Test Mode Works

Test IP Addresses

Use these IP addresses to test different risk scenarios:

Test Email Addresses

Use these email addresses to test email validation scenarios: