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 permission-based. Each mutating route is mapped to the permission it requires in src/lib/rbac/route-permissions.ts, and a coverage test fails the build if a mutating route is missing from that map. Guards come from src/lib/apiAuth.ts (requireAuth, requirePermission). See Roles and Permissions.

Read and write on the same resource are separate permissions: GET takes the domain's :read permission, mutations take :manage (or the more specific action). In the tables below, the Requires column is one of:

• a permission string, enforced by requirePermission
• session for any authenticated user, no specific permission
• public for routes that carry their own authentication (bearer token, single-use token) or none at all

Authentication

Endpoint	Method	Requires	Description
/api/auth/[...all]	*	public	Better Auth handler: sign-in, session, SSO callbacks, passkeys, TOTP
/api/sso/resolve	POST	public	Given a typed email, report whether that company has a verified SSO provider. Runs before sign-in, so there is no session yet.
/api/invitations/accept	POST	public	Accept an invitation. The single-use token in the body is the authorization; the invitee has no account yet.
/api/account/password	POST	public	Change your own password. Checks the session directly, because a user under a forced rotation is refused everywhere else and this is the one call that must still go through. Re-verifies the current password.

Sessions are issued by Better Auth. src/middleware.ts protects every route except api/auth, static assets and /login. See Authentication.

Identity and access

Endpoint	Method	Requires	Description
/api/rbac/step-up	POST	session	Re-enter your password to obtain a 5-minute step-up grant
/api/roles	GET	roles:read	List roles
/api/roles	POST	roles:manage	Create a role
/api/roles/[id]	PATCH/DELETE	roles:manage	Update / delete a role
/api/users	GET	users:read	List users
/api/users	POST	users:manage	Create a user
/api/users/[id]/role	PATCH	users:manage	Assign a role
/api/users/[id]/invite	POST	users:manage	Send an invitation
/api/users/[id]/require-password-change	POST	users:manage	Force a password rotation at next sign-in
/api/sso/provider	POST/PATCH/DELETE	sso:config	Manage the company OIDC provider
/api/sso/provider/domain	POST	sso:config	Verify the provider's email domain
/api/audit	GET	audit:read	Read the audit log

Creating a role that holds a crown-jewel permission, or assigning one, also requires a fresh step-up grant and passes the no-escalation subset check. See Roles and Permissions.

Company settings

Endpoint	Method	Requires	Description
/api/company	PATCH	policy:manage	Scan interval, risk weights, remediation toggle, SIEM token and push config
/api/company/auth-policy	PATCH	policy:manage	Allowed second factors and whether SSO is mandatory

Employees and scanning

Endpoint	Method	Requires	Description
/api/employees/scan	POST	employees:scan	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	Requires	Description
/api/alerts/[id]	PATCH	alerts:status	Update an alert's status (OPEN / ACKNOWLEDGED / RESOLVED)
/api/alerts/[id]/remediate	POST	alerts:remediate	Revoke sessions / force reset for the alert's employee

Remediation additionally requires remediationEnabled on the company, else 403. See Remediation.

Exposure register

Endpoint	Method	Requires	Description
/api/register	GET	register:read	List entries
/api/register	POST	register:manage	Create an entry
/api/register/[id]	PATCH	register:manage	Update status / assessment
/api/register/[id]/evidence	GET	register:evidence	Download the evidence CSV

See Exposure Register.

Credentials (breach-provider API keys)

Endpoint	Method	Requires	Description
/api/credentials	GET	api_credentials:read	List provider keys
/api/credentials	POST	api_credentials:manage	Add a provider key
/api/credentials/[id]	DELETE	api_credentials:manage	Remove a provider key

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

Directory connections

Endpoint	Method	Requires	Description
/api/directory	GET	connectors:read	List connections
/api/directory	POST	connectors:manage	Create a connection
/api/directory/[id]	PATCH/DELETE	connectors:manage	Update / delete a connection
/api/directory/[id]/test	POST	connectors:sync	Validate credentials, return user count
/api/directory/[id]/sync	POST	connectors:sync	Trigger a sync (rejected for SCIM)

See Directory Integrations.

SCIM (inbound provisioning)

Endpoint	Method	Requires	Description
/api/scim/[connectionId]/Users	GET/POST	public (bearer)	List / create users
/api/scim/[connectionId]/Users/[scimId]	GET/PUT/DELETE	public (bearer)	Read / replace / delete a user

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

Dashboard

Endpoint	Method	Requires	Description
/api/dashboard/config	GET/PUT	session	Read / save the user's live layout
/api/dashboard/presets	GET/POST	session	List / create presets
/api/dashboard/presets/[id]	PATCH/DELETE	session	Rename / delete a preset
/api/dashboard/presets/[id]/activate	POST	session	Activate a preset
/api/dashboard/detail/[kind]/[id]	GET	employees:read	Drill-down data behind a widget

Notifications (webhooks and channels)

Endpoint	Method	Requires	Description
/api/webhooks	GET	notifications:read	List channels
/api/webhooks	POST	notifications:manage	Create a channel (webhook, Slack, Teams, email)
/api/webhooks/[id]	PATCH/DELETE	notifications:manage	Update / delete a channel
/api/webhooks/[id]/test	POST	notifications:manage	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	Requires	Description
/api/reports/export	GET	reports:export	Export the current report. format=pdf returns a PDF, otherwise CSV.
/api/reports/schedules	GET	reports:read	List scheduled deliveries
/api/reports/schedules	POST	reports:schedule	Create a scheduled delivery
/api/reports/schedules/[id]	PATCH/DELETE	reports:schedule	Update / delete a schedule

See Reports.

SIEM export

Endpoint	Method	Requires	Description
/api/integrations/siem/[companyId]	GET	public (bearer)	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	Requires	Description
/api/health	GET	public	Liveness / readiness healthcheck
/api/cron	POST	public (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 bearer token)
403	Forbidden. Missing permission, remediation disabled, or code: "STEP_UP_REQUIRED" when a crown-jewel action needs a fresh re-auth
409	Conflict (scan already running)
429	Rate limited
502	Upstream failure (provider call during remediation)
503	Precondition unmet (no breach provider configured, or CRON_SECRET unset)