Admin API

This endpoint requires admin-level roles (platform_admin, tenant_admin, or system_admin). Accessible via the API gateway at /v1/platform/*.

Threat Detection API

Security monitoring, fraud prevention, anomaly detection, and threat analysis.

Overview

Attribute	Value
Base Path	`/api/v1/security/threats`
Authentication	Bearer Token
Required Roles	`platform_admin`, `system_admin`, `super_admin`

Threat Monitoring

Get Threat Dashboard

Real-time security overview.

GET /api/v1/security/threats/dashboard

Query Parameters

Parameter	Type	Description
`tenant_id`	uuid	Filter by tenant
`location_id`	uuid	Filter by location
`period`	string	`1h`, `24h`, `7d`, `30d`

Response

{
  "period": "24h",
  "summary": {
    "threat_level": "low",
    "active_threats": 2,
    "blocked_attempts": 45,
    "suspicious_activities": 12,
    "security_score": 92
  },
  "threats_by_type": [
    {"type": "fraud_attempt", "count": 8, "blocked": 8},
    {"type": "suspicious_login", "count": 15, "blocked": 12},
    {"type": "rate_limit_abuse", "count": 22, "blocked": 22},
    {"type": "data_exfiltration", "count": 0, "blocked": 0}
  ],
  "risk_distribution": {
    "critical": 0,
    "high": 2,
    "medium": 8,
    "low": 35
  },
  "trending": {
    "direction": "improving",
    "change_percent": -15
  }
}

Threat Level Values

Level	Description
`critical`	Immediate action required
`high`	Elevated threat activity
`medium`	Moderate concern
`low`	Normal operations

List Active Threats

GET /api/v1/security/threats

Query Parameters

Parameter	Type	Description
`status`	string	`active`, `investigating`, `resolved`
`severity`	string	`critical`, `high`, `medium`, `low`
`type`	string	Threat type filter

Response

{
  "data": [
    {
      "id": "threat_001",
      "type": "fraud_attempt",
      "severity": "high",
      "status": "active",
      "description": "Multiple failed payment attempts with different cards",
      "source": {
        "ip": "192.168.1.100",
        "user_agent": "Mozilla/5.0...",
        "location": "Unknown VPN"
      },
      "target": {
        "type": "payment_endpoint",
        "resource": "/api/v1/payments"
      },
      "indicators": [
        {"type": "velocity", "detail": "15 attempts in 5 minutes"},
        {"type": "card_testing", "detail": "Sequential card numbers"},
        {"type": "geo_mismatch", "detail": "IP location differs from billing"}
      ],
      "actions_taken": [
        {"action": "ip_blocked", "timestamp": "2026-01-24T19:15:00Z"},
        {"action": "alert_sent", "timestamp": "2026-01-24T19:15:01Z"}
      ],
      "detected_at": "2026-01-24T19:14:00Z",
      "assigned_to": null
    }
  ]
}

Get Threat Details

GET /api/v1/security/threats/{threat_id}

Response

{
  "id": "threat_001",
  "type": "fraud_attempt",
  "severity": "high",
  "status": "investigating",
  "timeline": [
    {
      "timestamp": "2026-01-24T19:10:00Z",
      "event": "First suspicious activity detected"
    },
    {
      "timestamp": "2026-01-24T19:14:00Z",
      "event": "Threat threshold exceeded"
    },
    {
      "timestamp": "2026-01-24T19:15:00Z",
      "event": "Automatic blocking triggered"
    }
  ],
  "evidence": {
    "logs": [...],
    "related_events": [...],
    "affected_resources": [...]
  },
  "recommendations": [
    {
      "action": "review_blocked_transactions",
      "priority": "high",
      "description": "Review the 15 blocked transactions for legitimate attempts"
    }
  ]
}

Update Threat Status

PATCH /api/v1/security/threats/{threat_id}

Request Body

{
  "status": "resolved",
  "resolution": "confirmed_fraud",
  "notes": "Confirmed card testing attack. All attempts blocked successfully."
}

Fraud Detection

Analyze Transaction

Check transaction for fraud indicators.

POST /api/v1/security/fraud/analyze

Request Body

{
  "transaction": {
    "amount": 250.00,
    "currency": "USD",
    "card_last4": "4242",
    "card_country": "US",
    "billing_address": {
      "zip": "94105",
      "country": "US"
    }
  },
  "context": {
    "customer_id": "cust_abc",
    "ip_address": "192.168.1.50",
    "device_id": "device_xyz",
    "order_id": "ord_123"
  }
}

Response

{
  "risk_score": 25,
  "risk_level": "low",
  "recommendation": "allow",
  "signals": [
    {
      "signal": "known_customer",
      "impact": "positive",
      "score_impact": -15,
      "detail": "Customer with 25 previous orders"
    },
    {
      "signal": "consistent_location",
      "impact": "positive",
      "score_impact": -10,
      "detail": "Order from usual location"
    },
    {
      "signal": "large_order",
      "impact": "neutral",
      "score_impact": 5,
      "detail": "Order 50% above average"
    }
  ],
  "velocity_checks": {
    "orders_last_hour": 1,
    "orders_last_day": 2,
    "cards_last_day": 1,
    "status": "normal"
  }
}

Risk Levels

Level	Score Range	Action
`low`	0-30	Auto-approve
`medium`	31-60	Review recommended
`high`	61-80	Manual review required
`critical`	81-100	Auto-block

Get Fraud Rules

GET /api/v1/security/fraud/rules

Response

{
  "rules": [
    {
      "id": "rule_001",
      "name": "High Velocity",
      "description": "Block if >5 orders per hour",
      "condition": "orders_per_hour > 5",
      "action": "block",
      "score_impact": 40,
      "enabled": true
    },
    {
      "id": "rule_002",
      "name": "Card Country Mismatch",
      "description": "Flag if card country differs from IP country",
      "condition": "card_country != ip_country",
      "action": "flag",
      "score_impact": 25,
      "enabled": true
    }
  ]
}

Create Fraud Rule

POST /api/v1/security/fraud/rules

Request Body

{
  "name": "New Customer High Value",
  "description": "Review new customers with orders over $500",
  "condition": "is_new_customer AND order_amount > 500",
  "action": "review",
  "score_impact": 30
}

Anomaly Detection

Get Anomalies

GET /api/v1/security/anomalies

Query Parameters

Parameter	Type	Description
`category`	string	Anomaly category
`severity`	string	Filter by severity
`start_date`	datetime	Period start

Response

{
  "data": [
    {
      "id": "anomaly_001",
      "category": "transaction_pattern",
      "severity": "medium",
      "description": "Unusual spike in refund requests",
      "baseline": {
        "metric": "refunds_per_hour",
        "normal_range": [2, 8],
        "current_value": 25
      },
      "deviation": 3.2,
      "detected_at": "2026-01-24T18:00:00Z",
      "status": "investigating"
    },
    {
      "id": "anomaly_002",
      "category": "access_pattern",
      "severity": "low",
      "description": "Admin login from new location",
      "details": {
        "user": "admin@example.com",
        "location": "New York, NY",
        "usual_location": "San Francisco, CA"
      }
    }
  ]
}

Anomaly Categories

Category	Description
`transaction_pattern`	Unusual transaction behavior
`access_pattern`	Login/access anomalies
`data_access`	Unusual data queries
`api_usage`	API call anomalies
`inventory`	Inventory discrepancies

Configure Anomaly Detection

PUT /api/v1/security/anomalies/config

Request Body

{
  "sensitivity": "medium",
  "categories": {
    "transaction_pattern": {
      "enabled": true,
      "threshold_multiplier": 2.5
    },
    "access_pattern": {
      "enabled": true,
      "alert_on_new_location": true
    }
  },
  "baseline_window_days": 30
}

IP Management

List Blocked IPs

GET /api/v1/security/ip/blocked

Response

{
  "data": [
    {
      "ip": "192.168.1.100",
      "reason": "fraud_attempt",
      "blocked_at": "2026-01-24T19:15:00Z",
      "expires_at": "2026-01-25T19:15:00Z",
      "auto_blocked": true,
      "threat_id": "threat_001"
    }
  ]
}

Block IP

POST /api/v1/security/ip/block

Request Body

{
  "ip": "192.168.1.200",
  "reason": "manual_block",
  "duration_hours": 24,
  "notes": "Suspicious activity reported"
}

Unblock IP

DELETE /api/v1/security/ip/blocked/{ip}

List Allowlisted IPs

GET /api/v1/security/ip/allowlist

Add to Allowlist

POST /api/v1/security/ip/allowlist

Request Body

{
  "ip": "10.0.0.0/24",
  "description": "Corporate office range"
}

Security Alerts

List Alerts

GET /api/v1/security/alerts

Response

{
  "data": [
    {
      "id": "alert_001",
      "type": "threat_detected",
      "severity": "high",
      "title": "Potential fraud attack detected",
      "message": "Multiple card testing attempts blocked",
      "threat_id": "threat_001",
      "created_at": "2026-01-24T19:15:00Z",
      "acknowledged": false,
      "acknowledged_by": null
    }
  ]
}

Acknowledge Alert

POST /api/v1/security/alerts/{alert_id}/acknowledge

Configure Alert Rules

PUT /api/v1/security/alerts/rules

Request Body

{
  "rules": [
    {
      "condition": "threat_severity == 'critical'",
      "channels": ["email", "sms", "slack"],
      "recipients": ["security@example.com"],
      "immediate": true
    },
    {
      "condition": "threat_severity == 'high'",
      "channels": ["email", "slack"],
      "recipients": ["security@example.com"],
      "immediate": false,
      "digest_frequency": "hourly"
    }
  ]
}

Audit Log

Get Security Audit Log

GET /api/v1/security/audit

Query Parameters

Parameter	Type	Description
`action`	string	Filter by action type
`user_id`	string	Filter by user
`resource`	string	Filter by resource
`start_date`	datetime	Period start
`end_date`	datetime	Period end

Response

{
  "data": [
    {
      "id": "audit_001",
      "timestamp": "2026-01-24T19:30:00Z",
      "action": "ip_blocked",
      "actor": {
        "type": "system",
        "id": "fraud_detector"
      },
      "resource": {
        "type": "ip",
        "id": "192.168.1.100"
      },
      "details": {
        "reason": "fraud_attempt",
        "threat_id": "threat_001"
      },
      "ip_address": null
    }
  ]
}

Compliance Reports

Generate Security Report

POST /api/v1/security/reports

Request Body

{
  "report_type": "security_summary",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "format": "pdf",
  "include": ["threats", "anomalies", "blocked_ips", "audit_log"]
}

Webhooks

Event	Description
`security.threat_detected`	New threat detected
`security.threat_resolved`	Threat resolved
`security.fraud_blocked`	Fraud attempt blocked
`security.anomaly_detected`	Anomaly detected
`security.ip_blocked`	IP address blocked
`security.alert_triggered`	Security alert

Error Responses

Status	Code	Description
400	`invalid_ip`	IP address format invalid
400	`invalid_rule`	Rule condition invalid
404	`threat_not_found`	Threat ID not found
409	`ip_already_blocked`	IP already in blocklist

Security Best Practices - Security guide
Authentication - Auth security
Audit API - Audit logging

Overview​

Threat Monitoring​

Get Threat Dashboard​

Threat Level Values​

List Active Threats​

Get Threat Details​

Update Threat Status​

Fraud Detection​

Analyze Transaction​

Risk Levels​

Get Fraud Rules​

Create Fraud Rule​

Anomaly Detection​

Get Anomalies​

Anomaly Categories​

Configure Anomaly Detection​

IP Management​

List Blocked IPs​

Block IP​

Unblock IP​

List Allowlisted IPs​

Add to Allowlist​

Security Alerts​

List Alerts​

Acknowledge Alert​

Configure Alert Rules​

Audit Log​

Get Security Audit Log​

Compliance Reports​

Generate Security Report​

Webhooks​

Error Responses​

Related Documentation​

Overview

Threat Monitoring

Get Threat Dashboard

Threat Level Values

List Active Threats

Get Threat Details

Update Threat Status

Fraud Detection

Analyze Transaction

Risk Levels

Get Fraud Rules

Create Fraud Rule

Anomaly Detection

Get Anomalies

Anomaly Categories

Configure Anomaly Detection

IP Management

List Blocked IPs

Block IP

Unblock IP

List Allowlisted IPs

Add to Allowlist

Security Alerts

List Alerts

Acknowledge Alert

Configure Alert Rules

Audit Log

Get Security Audit Log

Compliance Reports

Generate Security Report

Webhooks

Error Responses

Related Documentation