#84 — Public REST API + webhooks

Closed during the 2026-08-23 GitHub migration: this epic already lives on GitHub as wayfinder map #269 (Roadmap #84 publication map: open REST API + webhooks to entitled firms) with live children #273/#274 (both ready-for-human). The plan is delivered at docs/product/public-api-plan.md awaiting owner decisions P1-P6. Continue there: https://github.com/Firmary/firmary-os/issues/269

Agent A — plan delivered (docs/product/public-api-plan.md, on dev at b806e3c). Moving to Under Review.

The one-paragraph version: headless = every UI workflow completable via API, and the architecture already makes that cheap — every server action is a thin wrapper over a module API, so REST is just a second transport: /api/v1 handlers ~10 lines each (token -> ActionCtx -> the SAME module API -> shared error mapper). Machine callers are the agent principals from the #56 plan (Logto M2M short-lived tokens; per-integration principals with their own role/segment scope/rate limit — 'Zapier', 'QBO bridge', 'reporting script' each visible in the audit trail). OpenAPI is GENERATED from the existing Zod validators so the spec can't drift. Webhooks are an outbox consumer, not a new event system: two additive tables (endpoints + deliveries), HMAC-signed posts, relay-native retries, auto-disable on repeated failure, admin CRUD with a delivery log. Phase A = tokens + read endpoints + OpenAPI; B = webhooks + first writes (after the current migration lane clears); C = full write parity tracked as an honest checklist.

Decisions for you: P1–P6 in the doc (token model, master keys or not, webhook event catalog size, write posture — same answer as #56 D3, docs hosting, GA gating).

Agent A claiming the PLAN you asked for (this card + its sibling — same headless goal, planned together so the REST and MCP surfaces share one principal/auth/authz story, interlocking with the agents-as-staff plan from #56). Deliverable: a design doc per card with explicit owner decisions; no code in this slice. Implementation of the webhooks piece stays deferred until Agent B?s in-flight migration lands (concurrent-migration stop condition). Started: 2026-07-09 07:25 America/Chicago.

@claude please create a plan for this using best practices. the goal is to be able to run the whole app headless if someone wants to