App security model v2

Flowgear separates an App's user interface from the authority to run its backend workflows. The frontend is public client-side code and API Keys are used to control which users are able to invoke specific Workflows (via Cookie-based Keys).

Treat the frontend as public

A published App is a collection of static files loaded into a sandboxed frame in the Flowgear Console. The sandbox limits browser capabilities, but it is not a secret store. A user can inspect downloaded JavaScript, browser storage, network messages, and values rendered by the App.

Do not include any of these in the frontend package:

Connection credentials or masked Connection values.
Token-based API Keys.
Private signing keys or client secrets.
Data that every authorized App user should not be able to inspect.

Build-time environment variables are not secret when their values are compiled into the frontend. Keep secrets in Flowgear Connections or another server-side store and access them only from a Workflow.

Separate visibility from authorization

Assigning an App to a Site makes it available in that Site's Console navigation to users who can list Site Apps. It does not grant the App permission to invoke every Workflow in the Site.

Similarly, removing an App from a Site removes that navigation entry, but it should not be the only control used to revoke backend access. Disable or update the relevant API Keys and release state when access to a Workflow must end immediately.

An embedded App uses Flowgear.Sdk.invoke instead of handling a credential. The Console validates the signed-in session and calls the selected Environment's Workflow endpoint on behalf of the App.

The call is authorized only when an enabled Cookie-based Key for that Environment permits both:

The signed-in user.
The target Workflow.

When Environment-scoped permissions are enabled, permitted users are further limited to users who can access that Environment. Give an App access only to the minimum Workflow set it requires, and remove users who no longer need the App's operations.

Cookie-based calls are associated with the signed-in username in Workflow execution context and logs. Review Workflow logs for backend operations and the App audit trail for package publish and Site-assignment changes.

Protect standalone access with a Token-based Key

A standalone frontend does not have the Console's session or invocation bridge. It calls the Environment hostname directly and must authenticate with a Token-based Key that permits the required Workflows.

Do not ship a reusable token in public browser code. Use a trusted server-side component to hold the token when the standalone application cannot protect it. If you discover you have accidentally compromised a token, you can rotate the affected API Key by cycling its tokens.

Control browser origins at the Environment

Flowgear evaluates browser origins against the target Environment's Allowed origins setting, see CORS and allowed origins for more on this topic.

Embedded Console origins are handled by the platform. For a standalone browser application, add each exact application origin to the Environment.

Avoid * unless every browser origin is intentionally trusted. Do not add Access-Control-* headers in an HTTP Workflow; Flowgear creates the CORS response at the Environment boundary.

CORS restricts browser behavior only, it does not affect the ability for a standalone app or script to invoke Flowgear and API Key authorization is always required.

Don't trust user-controlled input

Backing Workflows should treat every value from the App as untrusted input.

When a Workflow needs the context of the user invoking it, don't trust a user-provided Workflow Parameter. Only use the Context.CallerIdentity Parameter to determine which user or API key was used to invoke the Workflow. This Parameter is specially provided by the runtime and can't be externally overridden.

Additionally, the Workflow should:

Validate required fields, formats, ranges, and identifiers.
Recheck that the requested operation is permitted in the current business context.
Use least-privilege Connections.
Return only fields the caller needs.
Avoid writing secrets or sensitive payloads to logs.
Use small, deterministic mutations and safe retry behavior.

Frontend validation improves usability but does not enforce the backend rule. A caller can bypass or modify it.

Separate release decisions

App packages, Workflow revisions, API Keys, Site assignments, and Environment origins are changed independently. Review them as one release even though the Console manages them through different screens.

Before production rollout, confirm:

The App package contains no secrets and targets relative Workflow paths through the SDK.
The production Workflow revision matches the interface contract.
Cookie-based or Token-based Keys permit only the intended Workflows and principals.
Allowed origins contains only required standalone browser origins.
The App is assigned only to the intended Sites.
Success, validation failure, authorization failure, and external-system failure paths have been tested.
Workflow logs and App audit history provide enough evidence for support and review.