API Reference

API Reference

All endpoints are Next.js route handlers under src/app/api/. Unless noted, they return JSON and require an authenticated session. Authorization is centralized in src/lib/apiAuth.ts (requireAuth, requireAdmin); see Roles and Permissions.

Authentication

Endpoint	Method	Notes
/api/auth/[...nextauth]	*	Auth.js handler (login, session, callbacks)

Session cookies are issued by Auth.js. The middleware (src/middleware.ts) redirects unauthenticated users to /login for everything except api/auth, static assets, and the login page.

Employees and scanning

Endpoint	Method	Auth	Description
/api/employees/scan	POST	any user	Run a breach scan for the company. Rate-limited 5/min, one concurrent scan per company.

Responses: 200 { scanned, newRecords, newAlerts }, 429 (rate limited), 503 (no provider key), 409 (scan already running). See Breach Scanning.

Alerts

Endpoint	Method	Auth	Description
/api/alerts/[id]	PATCH	any user	Update an alert's status (OPEN / ACKNOWLEDGED / RESOLVED)
/api/alerts/[id]/remediate	POST	ADMIN	Revoke sessions / force reset for the alert's employee

Remediation requires remediationEnabled for the company, else 403. See Remediation.

Company settings

Endpoint	Method	Auth	Description
/api/company	PATCH	ADMIN	Update scan interval, risk weights, remediation toggle, SIEM token / push

Exposure register

Endpoint	Method	Auth	Description
/api/register	GET	any user	List register entries
/api/register	POST	ADMIN	Create an entry
/api/register/[id]	PATCH	ADMIN	Update status / assessment
/api/register/[id]/evidence	GET	any user	Download the evidence CSV

See Exposure Register.

Credentials (breach-provider API keys)

Endpoint	Method	Auth	Description
/api/credentials	GET/POST	ADMIN	List / add provider keys
/api/credentials/[id]	DELETE	ADMIN	Remove a provider key

Keys are encrypted at rest; only keyHint is returned for display.

Directory connections

Endpoint	Method	Auth	Description
/api/directory	GET/POST	ADMIN	List / create connections
/api/directory/[id]	PATCH/DELETE	ADMIN	Update / delete a connection
/api/directory/[id]/test	POST	ADMIN	Validate credentials, return user count
/api/directory/[id]/sync	POST	ADMIN	Trigger a sync (rejected for SCIM)

See Directory Integrations.

SCIM (inbound provisioning)

Endpoint	Method	Auth	Description
/api/scim/[connectionId]/Users	GET/POST	Bearer token	List / create users
/api/scim/[connectionId]/Users/[scimId]	GET/PUT/DELETE	Bearer token	Read / replace / delete a user

Authenticated by a per-connection bearer token, constant-time compared. See SCIM Provisioning.

Dashboard

Endpoint	Method	Auth	Description
/api/dashboard/config	GET/PUT	any user	Read / save the user's live layout
/api/dashboard/presets	GET/POST	any user	List / create presets
/api/dashboard/presets/[id]	PATCH/DELETE	any user	Rename / delete a preset
/api/dashboard/presets/[id]/activate	POST	any user	Activate a preset

Notifications (webhooks and channels)

Endpoint	Method	Auth	Description
/api/webhooks	GET/POST	ADMIN	List / create channels (webhook, Slack, Teams, email)
/api/webhooks/[id]	PATCH/DELETE	ADMIN	Update / delete a channel
/api/webhooks/[id]/test	POST	ADMIN	Send a test payload

Targets are encrypted at rest; payloads fire on new exposures at or above each channel's minSeverity. See Notifications and Security.

Reports

Endpoint	Method	Auth	Description
/api/reports/export	GET	any user	Export the current report as CSV
/api/reports/schedules	GET/POST	ADMIN	List / create scheduled deliveries
/api/reports/schedules/[id]	PATCH/DELETE	ADMIN	Update / delete a schedule

See Reports.

SIEM export

Endpoint	Method	Auth	Description
/api/integrations/siem/[companyId]	GET	Bearer token	Pull alerts as JSON / CEF / syslog (format, since)

Authenticated by a per-company export token, constant-time compared; 60 req/min. See SIEM Integration.

Operations

Endpoint	Method	Auth	Description
/api/health	GET	none	Liveness/readiness healthcheck
/api/cron	POST	Bearer CRON_SECRET	Run due scans, syncs, scheduled reports, and SIEM push

See Configuration for CRON_SECRET.

Status codes

Code	Meaning
200	Success
401	Unauthorized (no session, or bad SCIM token)
403	Forbidden (ADMIN-only route, or remediation disabled)
409	Conflict (scan already running)
429	Rate limited
502	Upstream failure (provider call during remediation)
503	Precondition unmet (no breach provider configured)