API Documentation
Quick Start
Base URL: https://api.blackicehq.com
Authentication: X-API-Key header
curl -X POST https://api.blackicehq.com/analyze \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"events":[{"user_id":"usr-001","timestamp":"2026-03-19T01:30:00Z","ip_address":"185.220.101.5","action":"login"}]}'
Endpoints
POST /analyze
Main fraud detection endpoint
{
"events": [EventObject]
}
EventObject fields:
- user_id (required)
- timestamp (required, ISO8601)
- ip_address (required)
- action (optional)
- device_id (optional)
- geo (optional)
- country (optional)
Response: summary, results[], usage
POST /access/request
Request API key
{
"email": "...",
"first_name": "...",
"last_name": "...",
"company": "...",
"job_title": "...",
"company_size": "...",
"industry": "...",
"use_case": "..."
}
POST /api/verify-token
Verify sandbox token
{
"token": "your_token"
}
Detection Rules
| Rule | Weight | Description |
|---|---|---|
| session_hijack | 0.85 | IP or device changed mid-session |
| impossible_travel | 0.80 | Geographically impossible location change |
| tor_exit | 0.75 | Connection via TOR anonymous network |
| ip_reuse | 0.70 | One IP used by multiple accounts |
| device_reuse | 0.70 | One device used by multiple accounts |
| repeated_failure | 0.65 | Multiple failed login attempts |
| RULE_CREDENTIAL_BRUTE_FORCE | 0.80 | Credential brute force — IP-level password rotation attack |
| RULE_INJECTION_SQLi | 0.85 | SQL injection — malicious SQL in request payload |
| RULE_INJECTION_NoSQLi | 0.85 | NoSQL injection — MongoDB operators in payload |
| RULE_INJECTION_CMDi | 0.90 | Command injection — shell commands in payload |
| RULE_INJECTION_XXE | 0.85 | XXE — XML entity expansion attack |
| RULE_NUMERIC_ABUSE | 0.88 | Numeric abuse — negative values, overflow, or discount manipulation |
| RULE_SEQUENTIAL_ENUMERATION | 0.80 | Sequential enumeration — sequential object ID access pattern |
| RULE_LOW_AND_SLOW | 0.70 | Low-and-slow attack — distributed requests evading thresholds |
| RULE_PHISHING_MALWARE_CHAIN | 0.85 | Phishing/malware chain — multi-step attack kill chain detected |
| RULE_TOKEN_REUSE_MULTI_DEVICE | 0.85 | Token reuse — same token used from multiple devices |
| RULE_TOKEN_REUSE_MULTI_COUNTRY | 0.90 | Token reuse — same token used from multiple countries |
| RULE_IDOR_BOLA | 0.80 | IDOR/BOLA — sequential or high-volume object ID enumeration |
| RULE_SESSION_HIJACK | 0.99 | Session hijack — token reused from different IP/device/country |
| RULE_SESSION_IMPOSSIBLE_TRAVEL | 0.90 | Impossible travel via session — distant countries within minutes |
| RULE_SESSION_DEVICE_ANOMALY | 0.70 | Session device change — unrecognized device used |
| RULE_SESSION_REACTIVATION_RISK | 0.60 | Session reactivation — dormant session reused after 24h+ |
| RULE_COOKIE_THEFT_SUSPECTED | 0.85 | Cookie theft — burst activity from new IP after stable session |
| RULE_STUFFING_BURST_IP | 0.70 | Credential stuffing — single IP failing logins across multiple accounts |
| RULE_STUFFING_BURST_USER | 0.65 | Password spraying — multiple failures against same account |
| FORBIDDEN_ENUMERATION | 0.75 | Path enumeration — 5+ HTTP 403s from same IP in 60s |
| ENV_VARIABLE_PROBE | 0.95 | Secrets probe — request targeting .env/config endpoints |
| OAUTH_SSO_ABUSE | 0.85 | OAuth/SSO abuse — token reused across users or IPs |
| login_payment_pattern | 0.65 | Login immediately followed by payment |
| velocity_spike | 0.55 | Unusually high action frequency |
| multiple_ips | 0.45 | Multiple IPs for single user |
| low_and_slow | 0.45 | Rare distributed actions over time |
| geo_ip_mismatch | 0.50 | IP country ≠ profile country |
| suspicious_hour | 0.25 | Activity between 1AM-5AM UTC |
| new_device | 0.20 | Unrecognized device |
| api_enumeration | 0.75 | API endpoint scanning / parameter probing |
| phishing_malware_chain | 0.90 | Phishing domain visit → file download → suspicious execution |
| idor_bola | 0.85 | Insecure Direct Object Reference — rapid enumeration of resource IDs |
| sequential_enumeration | 0.95 | Sequential/incremental ID enumeration — predictable object access pattern |
| session_hijack_detection | 0.88 | Session cookie theft — stable session taken over from new IP/device |
| token_multi_user | 0.90 | OAuth token shared across multiple user IDs |
Response Format
{
"verdict": "block",
"risk_score": 0.94,
"rules_fired": ["session_hijack", "tor_exit"],
"evidence_list": [
"IP changed mid-session",
"Connection via TOR exit node"
],
"narrative": "Session hijack detected: user logged in from a new device and TOR network."
}
Verdict Thresholds
- block — risk_score >= 0.75
- stepup — risk_score >= 0.50
- allow — risk_score < 0.50
Trial Limits
- 30 days free or 10,000 events
- After trial: $0.002/event