REST API Endpoints

AuroraSOC exposes 57 REST endpoints via FastAPI at http://localhost:8000. All endpoints (except /health and /api/v1/auth/token) require JWT authentication.

Authentication Flow

Base URL

http://localhost:8000/api/v1

Endpoints by Category

Authentication

Method	Path	Auth	Permission	Description
POST	/api/v1/auth/token	None	—	Get JWT access token

Request:

{
  "username": "admin",
  "password": "admin"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Users

Method	Path	Auth	Permission	Description
GET	/api/v1/users/me	JWT	—	Current user profile
GET	/api/v1/users	JWT	admin role	List all users
POST	/api/v1/users	JWT	admin role	Create user
DELETE	/api/v1/users/{username}	JWT	admin role	Delete user

System

Method	Path	Auth	Permission	Description
GET	/health	None	—	Public health check

Alerts

Method	Path	Auth	Permission	Description
GET	/api/v1/alerts	JWT	alerts:read	List alerts (paginated)
POST	/api/v1/alerts	JWT	alerts:write	Create alert
GET	/api/v1/alerts/{alert_id}	JWT	alerts:read	Get single alert
PATCH	/api/v1/alerts/{alert_id}	JWT	alerts:write	Update alert status

Query Parameters for GET /api/v1/alerts:

Param	Type	Default	Description
skip	int	0	Pagination offset
limit	int	50	Page size (max 200)
severity	string	—	Filter: critical|high|medium|low|info
status	string	—	Filter: new|triaged|investigating|...
source	string	—	Filter by source system

Alert creation includes deduplication:

dedup_hash = SHA256(f"{title}|{source}|{sorted(iocs)}")
# If matching hash exists, returns existing alert instead of creating duplicate

Cases

Method	Path	Auth	Permission	Description
GET	/api/v1/cases	JWT	cases:read	List cases
POST	/api/v1/cases	JWT	cases:write	Create incident case
GET	/api/v1/cases/{case_id}	JWT	cases:read	Get case with timeline
PATCH	/api/v1/cases/{case_id}	JWT	cases:write	Update case

Create Case Request:

{
  "title": "Lateral Movement via PsExec",
  "severity": "high",
  "description": "Multiple hosts showing PsExec activity",
  "alert_ids": ["uuid-1", "uuid-2"],
  "assignee": "analyst@example.com"
}

Agents

Method	Path	Auth	Permission	Description
GET	/api/v1/agents	JWT	agents:read	List all 16 agents
POST	/api/v1/agents/{id}/enable	JWT	agents:manage	Enable agent
POST	/api/v1/agents/{id}/disable	JWT	agents:manage	Disable agent
POST	/api/v1/agents/{id}/deploy	JWT	agents:manage	Deploy to site
PATCH	/api/v1/agents/{id}/scale	JWT	agents:manage	Scale instances (0-10)
POST	/api/v1/agents/investigate	JWT	investigation:trigger	Start investigation

Agent filtering parameters:

Param	Type	Description
site	string	Filter by SOC site
status	string	active|disabled|error
type	string	Agent type enum

Investigation request (rate-limited):

{
  "alert_context": "Suspicious DNS queries to known C2 domain t1.evil.com from 10.0.1.50",
  "has_cps_assets": false,
  "severity": "high"
}

Sites

Method	Path	Auth	Permission	Description
GET	/api/v1/sites	JWT	sites:read	List SOC sites
POST	/api/v1/sites	JWT	sites:manage	Register site
DELETE	/api/v1/sites/{id}	JWT	sites:manage	Remove site

SIEM

Method	Path	Auth	Permission	Description
GET	/api/v1/siem/logs	JWT	siem:read	Search logs
GET	/api/v1/siem/sources	JWT	siem:read	List log sources
GET	/api/v1/siem/stats	JWT	siem:read	SIEM statistics

EDR

Method	Path	Auth	Permission	Description
GET	/api/v1/edr/endpoints	JWT	edr:read	List endpoints
GET	/api/v1/edr/endpoints/{id}	JWT	edr:read	Endpoint detail
POST	/api/v1/edr/endpoints/{id}/isolate	JWT	edr:manage	Isolate endpoint
POST	/api/v1/edr/endpoints/{id}/unisolate	JWT	edr:manage	Remove isolation
POST	/api/v1/edr/endpoints/{id}/scan	JWT	edr:manage	Trigger scan
GET	/api/v1/edr/stats	JWT	edr:read	EDR statistics

SOAR

Method	Path	Auth	Permission	Description
GET	/api/v1/soar/playbooks	JWT	soar:read	List playbooks
GET	/api/v1/soar/playbooks/{id}	JWT	soar:read	Playbook details
POST	/api/v1/soar/playbooks/{id}/toggle	JWT	soar:manage	Toggle enabled
POST	/api/v1/soar/playbooks/{id}/execute	JWT	soar:execute	Execute playbook
GET	/api/v1/soar/executions	JWT	soar:read	Execution history
GET	/api/v1/soar/rules	JWT	soar:read	Automation rules
POST	/api/v1/soar/rules/{id}/toggle	JWT	soar:manage	Toggle rule

Playbooks

Method	Path	Auth	Permission	Description
GET	/api/v1/playbooks	JWT	playbooks:read	List playbooks
POST	/api/v1/playbooks/{id}/execute	JWT	playbooks:execute	Execute playbook
GET	/api/v1/playbooks/executions	JWT	playbooks:read	Execution history

CPS / IoT Devices

Method	Path	Auth	Permission	Description
GET	/api/v1/cps/devices	JWT	cps:read	List CPS devices
GET	/api/v1/cps/devices/{id}	JWT	cps:read	Device detail
POST	/api/v1/cps/devices/{id}/revoke	JWT	cps:manage	Revoke certificate
GET	/api/v1/cps/attestations	JWT	cps:read	Attestation results

Human Approvals

Method	Path	Auth	Permission	Description
GET	/api/v1/approvals	JWT	approvals:manage	List pending approvals
POST	/api/v1/approvals/{id}/decide	JWT	approvals:manage	Approve/deny

Decision request:

{
  "decision": "approved",
  "reason": "Verified - safe to isolate compromised host"
}

Reports

Method	Path	Auth	Permission	Description
GET	/api/v1/reports	JWT	reports:read	List reports
GET	/api/v1/reports/{id}	JWT	reports:read	Full report

Threat Intelligence

Method	Path	Auth	Permission	Description
GET	/api/v1/iocs	JWT	iocs:read	List IOCs
POST	/api/v1/iocs	JWT	iocs:write	Create IOC

Statistics & Dashboard

Method	Path	Auth	Permission	Description
GET	/api/v1/stats/overview	JWT	stats:read	Dashboard overview
GET	/api/v1/dashboard/stats	JWT	stats:read	Flat stats for frontend
GET	/api/v1/correlations	JWT	cps:read	Physical-cyber events
GET	/api/v1/firmware	JWT	cps:read	Firmware inventory

Rate Limiting

Endpoint Category	Rate Limit	Window
General API	100 req	per minute
Investigation trigger	10 req	per minute
Playbook execution	5 req	per minute

Error Responses

All errors follow a consistent format:

{
  "detail": "Alert not found"
}

Status Code	Meaning
400	Bad request / validation error
401	Missing or invalid JWT token
403	Insufficient permissions
404	Resource not found
429	Rate limit exceeded
503	Database unavailable (degraded mode)

Degraded Mode

When PostgreSQL is unavailable, the API automatically falls back to in-memory data stores with demo data. This ensures the dashboard and monitoring remain functional during database maintenance.

@app.exception_handler(DatabaseUnavailable)
async def _handle_db_unavailable(request, exc):
    return JSONResponse(
        status_code=503,
        content={"detail": "Database unavailable — running in degraded mode"},
    )