Public API v1 / Headless Platform: Release Report
Executive summary
The Public API v1 release promotes Lunnoa Automate from an interactively operated platform to a machine authenticated backend. Workspace scoped API keys let a client's own systems call a documented, versioned surface with the same RBAC, ownership, and licensing checks as a logged in user, opening the platform to OEM integrations and system to system automation.
At a glance
Lunnoa Automate becomes an embeddable automation backend, not just a product clients log into
Before this release, every action in Lunnoa required a human to sign in through the SPA. With API keys as service accounts, a client's core system, an internal portal, or an OEM partner product can call the platform directly, unlocking integration patterns that were not previously possible without a custom project.
Governance model carries over unchanged
Each API key provisions a SERVICE_ACCOUNT user with a normal RBAC role rather than a blanket bypass. Existing ownership and licensing checks apply to machine calls exactly as they do to human ones, so the new surface does not create a parallel, less governed access path.
What shipped
This release moves the headless platform and Public API v1 work from DEV to UAT. Four pieces of engineering work sit behind that one line summary.
Machine authentication as a first class login path
SuperAdmins mint workspace scoped keys (prefixed lna_) from Admin Space, API Keys. Each key provisions a SERVICE_ACCOUNT user with a normal RBAC role; the secret is shown once and stored server side as a sha256 hash rather than in plain text. A request carrying Authorization: Bearer lna_... resolves into the same request user shape as a JWT login, so downstream RBAC, ownership, and licensing checks do not need to know whether the caller was a human or a machine.
A curated, versioned public contract
Only operations tagged with @PublicApi() are exposed as part of the stable surface, flagged x-public: true in the OpenAPI schema. Filtered export and coverage checks enforce documentation quality on that tagged surface, so the contract a client integrates against is deliberately narrower and better documented than the full internal API.
Per key throttling
API traffic authenticated with a key is now rate limited per key instead of per source IP, so one integration cannot exhaust the quota available to another system sharing the same network path.
Supporting work
| Area | What changed |
|---|---|
| OpenAPI / response contracts | Expanded Swagger DTOs and response schemas across agents, workflows, executions, objects, knowledge, queues, tasks, projects, variables, connections, webhooks, and workflow apps. |
| Executions | New execution path computation utility (with tests); UI polling logic extracted into use-execution-polling. |
| Admin UI | New Admin Space, API Keys page and create-key dialog: one-time secret reveal, workspace and role selection, optional expiry. |
| Agent / Action UI | Shared action UI utilities and output field components; chat action output card refactors. |
| Database | Migration 20260708170000_add_api_keys_service_accounts. |
| Documentation | docs/api-authentication.md, packages/server/docs/public-api.md, and OpenAPI updates. |
What this enables for corporate and financial services clients
For IT and operations leadership evaluating Lunnoa, this release changes the shape of what "using Lunnoa" can mean. The platform stops being something a team logs into and starts being something a client's existing systems can call directly.
- Every action in Lunnoa requires an interactive session tied to a human user.
- Embedding Lunnoa inside an internal portal, a core banking system, or a partner product means a custom integration project, or scripting around the web UI.
- Machine traffic is throttled the same way as any other traffic from the same network path.
- SuperAdmins mint scoped `lna_...` keys tied to a normal RBAC role and a dedicated service account user.
- A client's own systems call the documented Public API v1 surface directly, with the same permission and licensing checks a human user would face.
- Each key's traffic is throttled independently, so one integration cannot starve another.
Why this matters by function
IT / Security leadership: a governed way to say yes to integration requests
Because every key is a scoped, revocable, RBAC bound service account rather than a shared admin credential, a CISO or IT Director can approve system to system access without approving broad platform access. Revoking a key immediately returns 401 on further calls, and secrets are never stored in plain text.
Operations leadership: automation embedded in the systems people already use
A COO or Head of Ops no longer needs every team member trained on the Lunnoa UI to benefit from it. Existing internal tools, whether a core banking platform, a document management system, or an internal ticketing portal, can trigger and consume Lunnoa workflows directly, which lowers the change management cost of a rollout.
Product and OEM partners: Lunnoa as an embedded engine, not a standalone product
Because the Public API v1 surface is documented, versioned, and access controlled per workspace, a partner, for example a core banking or case management vendor, can white-label Lunnoa's automation capability inside their own product rather than sending their users to a separate application.
Regulated financial institutions: a compliance story that holds together
Self-hosted deployment plus scoped, auditable machine credentials plus a curated public contract is a combination that tends to satisfy internal architecture and security review at banks and asset managers, where an undocumented or over-privileged integration path is often the sticking point in a proof of concept.
Governance, security, and rollout
Configuration
| Variable | Default | Purpose |
|---|---|---|
| API_KEYS_ENABLED | true (in .env.example) | Master switch for API key authentication |
UAT deployment checklist
The deploy notes define a short, concrete verification path for this release before it can be shown to clients or promoted further.
| Check |
|---|
| Migration applies cleanly on UAT |
| Admin Space, API Keys: create, list, revoke |
| API key auth succeeds on a tagged public endpoint within the key's role |
| Revoked, expired, or unknown key returns 401 |
| JWT session auth still works for the SPA |
| /docs and public OpenAPI export look correct |
| Execution polling and path responses behave as before in the UI |
| Agent chat action UI still renders outputs correctly |
Recommended next steps
Run the full UAT test plan before referencing this in client conversations
The deploy notes already define the smoke test: create a key, call a tagged public endpoint, revoke it, and confirm 401. Until that has been run end to end on UAT, the safest external framing is "in UAT testing" rather than "available".
Build a headless integration narrative into financial services pitches
Institutions such as Al-Tijari, Partners Group, and Albin Kistler are evaluating Lunnoa partly on integration risk. A short technical appendix showing scoped API keys, per-key rate limiting, and the curated Public API v1 contract gives their architecture and security reviewers something concrete to assess, rather than asking them to take governance on faith.
Write a one page API key governance note for CISO level conversations
Cover key issuance, one-time secret reveal, hashing at rest, expiry, and revocation in plain business language. This is the kind of artefact a bank's security team will ask for early in a proof of concept, and having it ready shortens the review cycle.
Evaluate an OEM / white-label pricing motion once the Public API v1 surface stabilises
A documented, versioned public contract is the technical precondition for a partner to embed Lunnoa inside their own product. Whether that becomes a second commercial motion alongside direct sales is a separate decision, but this release is what makes it feasible.