Skip to main content

The Four API Surfaces

The platform exposes four distinct API surfaces. They share one physical server process but use distinct middleware chains and serve different audiences — and keeping them straight is essential to understanding the system's trust boundaries. This is the map; each surface has its own authoritative contract document.

The four​

  1. Core API (UI ↔ backend). All operator-facing operations — auth, the configuration registries, system context and config, API-key management, dashboard and analytics. Audience: the admin app frontend (core shell + plugin UI). Auth: operator JWT.
  2. Workflow execution API — UI-facing. Starting a workflow from the UI, retrying, viewing execution history and logs. Audience: plugin UI components (e.g. the "Run Workflow" button). Auth: operator JWT.
  3. Workflow execution API — n8n-facing (the machine API). The engine reporting back during execution — logging steps, completing, terminating. Audience: the workflow engine, not any UI. Auth: API Key, over separate middleware. This is where the /logs response carries the abort flag that drives threshold self-termination.
  4. Plugin-owned API. Entity-specific operations a plugin chooses to expose (domain CRUD, custom side channels). Audience: defined by the plugin. Auth: currently operator JWT (plugin routes mount on the operator-protected router); plugins mount under their declared route prefix.

The rules that hold it together​

A few constraints keep the surfaces from blurring:

  • Distinct auth per surface. Surfaces 1, 2, and (currently) 4 use the operator JWT; surface 3 uses the API Key with its own middleware. Rate limiting applies across all four.
  • The core never calls plugin-owned endpoints. Domain result handling is delegated internally via the plugin manifest's resultHandler, not via an HTTP callback — so the plugin API is for the plugin's callers, never for the core.
  • Plugin endpoints don't duplicate or bypass the core. They may layer on top of the execution lifecycle but must not replace it, and must not mutate core tables except through core services.

Why name them separately​

Cite an endpoint's purpose and its authoritative contract, not a hardcoded path — endpoint names can change while a surface's role does not. The reason to treat these as four things rather than "the API" is that each is a different trust relationship: who's calling, with which credential, over which middleware. That framing is what lets the platform host operator traffic and machine traffic on one server without ever crossing the wires.