Security model

This page describes the security posture of the Public API. It is intended for partner security reviewers and SOC 2 / ISO auditors.

Threat model — what we defend against

Threat	Control
Bearer token replay	HMAC request signing with a 300 s timestamp window.
Bearer token theft from logs	SHA-256 hashed at rest; raw key shown only once. First-12-char prefix is the only piece safe to log.
Compromised network egress	Optional per-key IP allowlist.
Browser-origin abuse	Browser CORS pre-flight rejected by default. Server-to-server only.
Mass key sharing across orgs	Org scope enforced on every read and write. org_id mismatches return 403.
Token replay on results endpoint	result_token is single-use, 15-minute TTL, bound to one evaluation_id.
Webhook spoofing	Receivers verify HMAC over {ts}.{raw_body} using the subscription's signing_secret.
Leaked sanitised results	Per-response meta.watermark for downstream forensics.

What FlowBeacon sees

• Scenario blueprints already imported into your organization.
• Module configurations (types, scopes, connection metadata).
• Per-key request metadata (method, path hash, status, watermark, timestamp, IP, user-agent).

What FlowBeacon does not see

• Live module execution logs.
• The contents of records flowing through your scenarios at runtime.
• API keys for downstream services (Make, n8n, etc.) — those are referenced by connection ID, not value.
• Your customers' data. The platform only evaluates the shape of automation logic, not the data.

Defence in depth (in order of layering)

1. Transport — TLS 1.2+, HTTPS only in production.
2. Authentication — Bearer API key, SHA-256 hashed at rest.
3. Signature — HMAC-SHA-256 over the canonical request string, 300 s tolerance.
4. IP allowlist — optional per-key.
5. Organization scope — every record carries organization_id; mismatches return 403.
6. Permission scopes — governance:read, governance:evaluate, admin. Missing → 403.
7. Rate limits — per-key RPM (60) and RPH (1000) windows.
8. Anomaly detection — internal-only today, with an opt-in auto-suspend flag.
9. Watermarking — every response has a leak-tracing ID.
10. Kill switch — PUBLIC_API_ENABLED=false returns 503 across the surface.

Local development carve-outs

Flag	Default	Effect	Allowed in production?
PUBLIC_API_REQUIRE_HMAC	true	When false, the middleware does not require X-FB-Signature.	No. Does not exist in production.
PUBLIC_API_ENABLED	true	When false, the API returns 503 Public API is disabled for every route.	Yes (emergency kill switch).
PUBLIC_API_ANOMALY_AUTO_SUSPEND	false	When true, anomaly detector auto-suspends keys past thresholds.	Yes (opt-in).

Vulnerability disclosure

Report suspected vulnerabilities to security@flowbeacon.ai. Please include steps to reproduce, affected endpoints, and any proof-of-concept data. Do not include live customer data. Acknowledgement within one business day.

Next steps

• Authentication — the practical view.
• Versioning and stability — what changes break and what doesn't.