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)

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

Webhooks

Endpoint	Method	Auth	Description
/api/webhooks	GET/POST	ADMIN	List / create webhooks
/api/webhooks/[id]	PATCH/DELETE	ADMIN	Update / delete a webhook
/api/webhooks/[id]/test	POST	ADMIN	Send a test payload

Webhook URLs are encrypted at rest; payloads fire on new exposures at or above each webhook's minSeverity. See Security.

Reports

Endpoint	Method	Auth	Description
/api/reports/export	GET	any user	Export the current report as CSV

Status codes

Code	Meaning
200	Success
401	Unauthorized (no session, or bad SCIM token)
403	Forbidden (ADMIN-only route hit by a VIEWER)
409	Conflict (scan already running)
429	Rate limited
503	Precondition unmet (no breach provider configured)