Apps v2

Flowgear Apps are lightweight interfaces over Workflow-backed business logic. They give users a focused tool for work such as viewing operational status, resolving integration exceptions, or starting a controlled action without creating another system of record.

Use an App when an integration needs a human-facing interface. Keep system access, transformation, and process logic in Workflows so the same Connections, security controls, and logs remain available behind the interface.

How an App fits together

Layer	Responsibility
App frontend	Displays data, collects user intent, validates input, and calls a narrow Workflow API.
Flowgear Console	Hosts a published App, supplies signed-in context and theme, selects the Environment, and brokers Workflow calls from the embedded frontend.
Workflows	Connect to systems, enforce the business process, perform authorized operations, and return a response that the App can display.

The frontend package and Workflow revisions have separate lifecycles. Publishing a new App version does not release a Workflow revision, and releasing a Workflow does not rebuild the frontend.

Embedded Apps

A published Flowgear App is a static client-side application embedded in a sandboxed Console frame. It can use the Flowgear web App SDK to:

Read the current Tenant, Site, username, Account, theme, available Environments, and selected Environment.
Invoke published HTTP Workflows through the Console.
Display Console alerts, confirmation dialogs, and text prompts.
Open a URL and synchronize in-App navigation with the parent Console route.

See App Console SDK for the public methods and current result shapes.

Published Apps default to opening for the Production Environment (if available to the current user). During local development, the debug App opens against the first Environment (i.e. Test).

The static App files are publicly hosted client-side assets. Never place Connection values, API-key tokens, or other secrets in source code, environment values that are bundled into the build, or browser storage.

See App security model for the complete frontend, API-key, Workflow, origin, and release boundary.

Embedded authorization

An embedded App calls a Workflow with Flowgear.Sdk.invoke. The Console performs the request on behalf of the App and carries the current signed-in session, so the frontend does not handle an API-key token.

The request must still match a Cookie-based Key in the selected Environment. That key limits both:

Which users may invoke through it.
Which Workflows those users may invoke.

Being signed in to the Console does not grant the App access to every Workflow. Keep each Cookie-based Key limited to the users and Workflow endpoints required by that App.

Workflow backends

App-facing Workflows are HTTP-bound. A Workflow receives an HTTP request, uses server-side Connections and mappings to perform the work, then returns an HTTP response to the App.

Keep authorization and validation on the Workflow side even when the frontend validates the same input. A user can inspect or alter browser code, while Workflow execution remains inside the platform and is recorded in Workflow logs.

The Console's current Environment selects the published Workflow endpoint used by an embedded App. This lets the same interface work with development or production revisions, provided the required Workflow routes and Cookie-based Keys exist in each Environment.

Site assignment and App versions

An App package is published under a Flowgear Account. Its manifest supplies an internal Name, a Version, a user-facing DisplayName, and a navigation Rank.

After publishing a package, assign the App to one or more Sites. Site assignment controls where the App appears in Console navigation; it is separate from publishing the package. Publishing another Version under the same App name replaces its static content while retaining its Site assignments.

App publish, Site assignment, and Workflow release should be reviewed separately. Removing an App from all Sites is also required before the App can be deleted.

Standalone web apps

A web app hosted outside the Flowgear Console can use the same published HTTP Workflows, but it does not receive Console context or the embedded invocation bridge. It must authenticate directly with a Token-based Key that permits only the required Workflows. The token that is used by the app should not be present in the frontend code of the app.

For browser calls, add the frontend origin to the target Environment's Allowed origins. Flowgear manages the CORS response at the Environment boundary; do not add Access-Control-* headers inside the Workflow.

Agent-assisted development

The downloadable sample App contains a frontend scaffold, local development configuration, and an OpenAPI description of selected Workflow endpoints. Its repository guidance directs a coding agent to use the Flowgear SDK for frontend calls and Builder MCP for Workflow-backed APIs.

This lets an agent work across both layers: it can edit the interface in the local repository, discover and test exact Flowgear contracts through Builder MCP, and then bind the frontend to the tested Workflow route. You still review external side effects, authentication scope, the generated frontend, and every Workflow before publish.