UI Implementation Guide

For the team building the UI on top of the platform. The UI is a thin client over the /api/v1 REST API — every screen and button maps to one of the endpoints in the API Reference. This page lists, per module, what control to build, the API call behind it, and what it does.

Common patterns (build these once)

• Auth. Every request carries X-Master-Key + X-Admin-Key; org-scoped requests also carry X-Org-Key. Keys live server-side (a BFF/proxy), never in the browser. See API Overview.

• Start-a-scan + poll. Every module's "Run" button is the same call — POST /org/scans with the module key — then poll progress:

• Gate the Run button. Each module has a status endpoint returning can_run; disable "Run" (with the reason) when it's false.

• Cooldown. POST /org/scans enforces one scan per module per ~14 days; show the next-eligible time and handle 409 (already in cooldown / in flight).

• Errors to handle everywhere: 401 (bad key), 403 (module not enabled), 404, 409 (gate/cooldown), 422 (validation).

EASM — screens & controls

Screen / control	API call	What it does
Domains list	GET /org/domains	Show the org's seed domains.
Add domains button → input	POST /org/domains (201)	Add one or more domains to scan.
Edit domain	PATCH /org/domains/{domain_id}	Change a domain (e.g. enable/disable).
Remove domain (🗑)	DELETE /org/domains/{domain_id} (204)	Remove a domain.
Run EASM scan button	POST /org/scans {"module":"easm"}	Start a scan. Gate: requires ≥1 domain (else 400).
Scan progress	GET /org/scans/{id}/progress	Live per-scanner progress; drive a progress bar.
Findings (grouped)	GET /org/findings/grouped	The main results view (grouped by issue + affected assets).
Findings (flat) / filters	GET /org/findings	Filterable list (severity, status, …).

DAST — screens & controls

DAST tests web apps that EASM discovered, so its UI is gated on a non-empty surface.

Screen / control	API call	What it does
Surface list	GET /org/dast/surface	The web apps EASM found — what DAST can test.
Run DAST button	POST /org/scans {"module":"dast"}	Start an active web-app scan. Gate: GET /org/dast/status → can_run; 409 "DAST requires a completed EASM scan that discovered web apps" if the surface is empty.
Status / gate	GET /org/dast/status	Drives the enabled/disabled state + reason on the Run button.
Progress / findings	(same scan + findings endpoints as EASM)	—

Cloud (CSPM) — screens & controls

Screen / control	API call	What it does
Connected accounts list	GET /org/aws/accounts	Show connected AWS accounts + their status (pending / validated / invalid).
Connect AWS account (step 1)	POST /org/aws/accounts (201)	Create the account record; the response carries the External ID + assumer ARN to display for the customer's CloudFormation step.
Attach role ARN (step 2)	POST /org/aws/accounts again, with role_arn	Save the read-only role ARN the customer created (updates in place; status → pending).
Validate button	POST /org/aws/accounts/{id}/validate	Live test-AssumeRole; sets status validated / invalid (with reason).
Disconnect (🗑)	DELETE /org/aws/accounts/{id} (204)	Remove the stored connection.
Run cloud scan button	POST /org/scans {"module":"aws"}	Scan all validated accounts. Gate: GET /org/aws/status → can_run; 409 "AWS requires a validated cloud account" otherwise.
Status / gate	GET /org/aws/status	{enabled, validated_accounts, can_run} — drives the Run button.
Posture table (pass + fail)	GET /org/aws/results	The compliance/posture view; supports filters status, framework, service, severity, account, limit, offset.
Framework dropdown	GET /org/aws/frameworks	The frameworks present in results (CIS, ISO 27001, SOC 2, NIST, PCI…) — drives the "pick your standard" filter.
Compliance report	GET /org/aws/compliance	A structured compliance report for the selected framework.

The detailed customer-facing setup that sits behind "Connect AWS" is Connecting AWS.

Cross-cutting: Findings & Tasks (all modules)

Screen / control	API call	What it does
Findings (grouped / flat)	GET /org/findings/grouped, GET /org/findings	Results across modules; filter by module to scope to one.
Finding detail	GET /org/findings/{id}	Full finding (description, risk, remediation steps, evidence).
Triage (false-positive / accept-risk / mark-resolved)	PATCH /org/findings/{id}	Record the customer's verdict; feeds re-scan reconciliation.
Finding history	GET /org/findings/{id}/history	The status timeline for a finding.
Tasks board	GET /org/tasks	Remediation tasks derived from findings.
Activity feed	GET /org/activity	The org audit trail (who did what, when).
Scans history	GET /org/scans, GET /org/scans/{id}	Past + current scans; POST /org/scans/{id}/stop to cancel.

One UI, three modules. The scan lifecycle, findings, tasks, triage, and activity screens are shared — only the per-module setup (domains for EASM, surface gate for DAST, account connection for Cloud) differs. Build the shared screens once and switch the module key.