Anonymous runtime access

A runtime app can be configured for unauthenticated end users. Anonymous users start processes and UI flows from a public link, with no login required.

Overview

Anonymous runtime access lets an app serve users who have no FlowX identity. A typical use case is a public form, a quote calculator, or an appointment booking page reachable from a marketing site. Two independent gates must both be open for a request to be served anonymously:

The app must be shared publicly

In the Share modal, General access is set to Everyone with the link. Apps default to Only invited users and groups.

The resource must allow the Anonymous role

The specific process or UI flow being started must have the Anonymous role assigned in its Permissions tab.

If either gate is closed, the runtime returns 403 Forbidden with a detail of Anonymous access not enabled for this application (the app is not publicly shared) or Anonymous access not enabled for this build (the resource does not carry the Anonymous role). Mixed-access is supported — the same app can serve authenticated users with their assigned roles and anonymous users with the Anonymous role.

The Anonymous role

Anonymous is a built-in, system-level role. It represents any user who arrives without a valid authentication token.

Property	Value
Role type	System (built-in)
Editable	No — name, scope, and allowed operations are fixed
Deletable	No
Allowed operations	`VIEW`, `EXECUTE`, `SELF_ASSIGN`
Selectable operations in the UI	`VIEW` and `EXECUTE` only — `SELF_ASSIGN` is auto-populated and required
Default on a project	Not added — admin opts in via End User Roles in Version settings

SELF_ASSIGN is required because starting a process needs both EXECUTE and SELF_ASSIGN. The role auto-populates the three operations and locks SELF_ASSIGN so the role always behaves consistently across processes.

Make an app publicly accessible

Add the Anonymous role to the project

Open the project’s Version settings → End User Roles, then add Anonymous to the available roles.Until the role is on the version, the Share modal’s general-access dropdown stays disabled.

Open the Share modal

From the project header, click Share.

Set General access to Everyone with the link

Under Who has access → General access, switch from Only invited users and groups to Everyone with the link.

Switching back to Only invited users and groups at any point closes the public gate immediately. Existing anonymous sessions in flight will start returning 403 Anonymous access not enabled for this application on their next request.

Save and copy the share link

Save the Share modal. The runtime app is now reachable to anyone with the URL — subject to the per-resource role check below.

Configure anonymous on a resource

The Anonymous role must be explicitly assigned to each process, UI flow, or reusable UI template you want runnable without authentication.

Process
UI Flow
Reusable UI template

Open the process and go to Permissions.

Add Anonymous to the role list (only available when the role is on the version).
The role’s row shows VIEW, SELF_ASSIGN, and EXECUTE pre-populated. Toggle VIEW or EXECUTE as needed. All other operations are greyed out.
Adding Anonymous is additive — it does not affect other roles on the process.

Anonymous can also be added to a swimlane. The component hide/disable rules below depend on this assignment.

Component visibility for anonymous users

UI Designer hide/disable rules support the Anonymous role in the Role condition type. The role must already be assigned at the right scope:

Component lives in…	Anonymous must be on…
A process node	The corresponding swimlane
A UI flow	The UI flow’s Permissions tab
A reusable UI template	The process version’s End User Roles

Common patterns:

Hide for anonymous — show a “Sign in to continue” CTA only when the user is anonymous; hide an action button (e.g. “Save to account”) for anonymous users.
Disable for anonymous — keep a field visible but read-only; the same field becomes editable for authenticated users.

Runtime behaviour scenarios

#	App general access	Resource has Anonymous role	User	Outcome
1a	Everyone with the link	Yes	Anonymous	Starts and uses the resource with Anonymous permissions.
1b	Everyone with the link	Yes (Anonymous is the only role)	Authenticated	Starts with the same permissions Anonymous grants — the logged-in user is effectively treated as anonymous for that resource.
1c	Everyone with the link	Yes (Anonymous + at least one other role)	Authenticated and assigned one of the other roles	Uses the assigned role; Anonymous is ignored.
2a	Only invited users and groups	n/a	Anonymous	`403` — `Anonymous access not enabled for this application`
2b	Everyone with the link	No	Anonymous	`403` — `Anonymous access not enabled for this build`

The anonymous session

Anonymous traffic is isolated using a session ID — there is no user identity to bind state to.

Header: X-Fx-Anonymous-Session-Id
Issued by: the backend, on the first anonymous request that doesn’t already carry one. The new session ID comes back in the response header X-Fx-Anonymous-Session-Id (exposed via Access-Control-Expose-Headers; the exposed-header list is controlled by the APPLICATION_CORS_EXPOSEDHEADERS env var, which carries this header by default).
Maintained by: the SDK / container app. After receiving the session ID, the client must include it on every subsequent anonymous request.
Scope: one anonymous session can only access the process and UI flow instances it created. Another session that knows the processInstanceUuid cannot read or act on it.
Lifetime: fire-and-forget. Closing the browser ends the session. There is no resume mechanism in 5.9.0.

Tokens take precedence over anonymous mode. If the client sends an Authorization: Bearer … header, the backend treats the request as authenticated and ignores the anonymous session ID. There is no fallback to anonymous when a bearer token is invalid or expired — the request returns 401.A common bug: a user logs in on /private, then opens /public in the same browser. The persisted bearer is attached to public-route requests and the backend returns the authenticated user’s data. Container apps must scrub the Authorization header on public routes — see SDK behaviour below.

Public build, public assets

Once a runtime build is published with the Anonymous role and the app is shared publicly, the build is considered public. All assets inside it are reachable anonymously — except UI flows and processes that have not been explicitly opened to the Anonymous role. Public assets in a public build:

Enumerations — /rtm/api/runtime/app/{appId}/build/{buildId}/rt/enumeration/...
Substitution tags — /rtm/api/runtime/app/{appId}/build/{buildId}/rt/substitutiontag
Media files — /rtm/api/runtime/app/{appId}/build/{buildId}/rt/mediafile
Themes — /cms/api/wks/{workspaceId}/themes/uuid/{themeId}/platform/{platform}/compiled (globally unauthenticated)
Fonts — /cms/api/fonts (globally unauthenticated)

Restricted assets (require authentication and a role grant):

UI flows not configured with Anonymous
Processes not configured with Anonymous
Chat, task manager, and view-scoped endpoints — see Restricted endpoints below

SDK and container app behaviour

Renderer initialization

Process and UI flow renderer components decide their mode at initialization from the authToken parameter:

authToken present (non-null) → renderer runs in authenticated mode. All outgoing requests carry the bearer token. If the token expires mid-flow the renderer surfaces 401 errors (existing behaviour).
authToken absent (null/undefined) → renderer runs in anonymous mode. The renderer omits the Authorization header and uses X-Fx-Anonymous-Session-Id instead.

The mode is locked at init. Switching authToken from null to a value after the renderer has started will not flip it into authenticated mode, and vice versa. If you need both modes in the same container app, mount separate renderer instances on separate routes (e.g. /public and /private).

Container apps

A container app that hosts both public and authenticated routes must guarantee that public routes do not pass an Authorization header to the renderer. The renderer uses an isolated HTTP client at runtime, so whatever the container does for its own pages does not automatically leak in — but if the container reads a token from localStorage and supplies it to the renderer, the token-precedence rule above applies and anonymous mode is silently bypassed. The recommended pattern:

Public route (e.g. /public/...) → mount renderer with authToken={null}
Private route (e.g. /private/...) → mount renderer with authToken={accessToken}
Clear any stored bearer when the user navigates from /private to /public.

Platform support

Capability	Web (React, Angular)	iOS	Android
Anonymous start of process / UI flow	✅	✅	✅
Anonymous session ID handling	✅	✅	✅
File uploads with anonymous session	✅	✅	✅
SSE streams (limited types)	✅	✅	✅
Task manager surfaces	n/a — restricted	n/a — restricted	n/a — restricted
Chat surfaces	n/a — restricted in 5.9.0	n/a — restricted in 5.9.0	n/a — restricted in 5.9.0

What anonymous users can call

Anonymous traffic is allowed on a curated set of runtime endpoints. The full reference is the SDK endpoint table — the summary below is grouped by capability. Endpoints flagged session ID required must include X-Fx-Anonymous-Session-Id; the backend rejects requests where the session ID does not match the entity it refers to (403 Anonymous session not found for entity).

Allowed

Capability	Endpoints	Session ID
Build info	`/rtm/api/runtime/wks/{wks}/app/{appId}/build/info` `/rtm/api/runtime/process-instance/{piUuid}/build/info` `/rtm/api/runtime/ui-flow-session/{sessionUuid}/build/info`	Required on the last two
Process — start	`POST /rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{name}/start` `POST /rtm/api/runtime/app/{appId}/build/{buildId}/process-rdi/{rid}/start`	Optional on start — issued by BE if missing
Process — status, data, details, actions, dismiss, subprocess	`GET /api/runtime/process/{piUuid}/status` `GET .../data`, `.../data/{templateConfigId}/context/{ctx}` `GET .../node/{nodeDefId}/context/{ctx}/details` `POST .../token/{tokenUuid}/ui-action/{uiActionUuid}/context/{ctx}/execute` `POST .../ui-action/.../subprocess` `POST .../dismiss`	Required
UI flow — start	`POST /rtm/api/runtime/app/{appId}/build/{buildId}/ui-flows/{name}` `POST /rtm/api/runtime/app/{appId}/build/{buildId}/ui-flow-rdi/{rid}`	Optional on start
UI flow — status, file upload	`GET /api/runtime/ui-flow-session/{uuid}/status` `POST /api/runtime/wks/{wks}/appId/{appId}/ui-flow/{uuid}/upload` `POST .../upload-multiple`	Required
Workflow — start from UI flow	`POST /rtm/api/runtime/wks/{wks}/app/{appId}/rdi/{rid}/start-workflow?uiFlowSessionUuid={uuid}`	Required. The user must also be authorized for the parent UI flow.
Data model paths (gated by Anonymous role on the resource)	`GET /rtm/api/runtime/process-instance/{piUuid}/data-model-paths` `GET .../app/{appId}/build/{buildId}/process-name/{name}/data-model-paths` (and equivalent for processes by `rdi`, and UI flows by `ui-flow-session`, `ui-flow-name`, `ui-flow-rdi`)	Required on the process-instance and ui-flow-session forms
CMS — enumerations, substitution tags, media	See Public build, public assets above	n/a
Themes, fonts	Globally unauthenticated	n/a
SSE — process instance	`GET /api/events/process-instance/{piUuid}?offset={offset}`	Required
SSE — generic, allowed types only	`GET /api/events/generic/{id}?type={type}&offset={offset}` Allowed types: `UI_FLOW_WORKFLOW_RESPONSE`, `UI_FLOW_FILE_UPLOAD`, `UI_FLOW_FILE_UPLOAD_MULTIPLE`	Required — used to correlate the entity with the session
File uploads (UI flow scope)	`POST /document/internal/wks/{wks}/temp-files/upload` `POST .../upload-multiple`	Required

Restricted endpoints

The following are never served anonymously, regardless of the public gates:

Task manager — every /rtm/api/runtime/app/.../view/... and /task/api/tasks/... endpoint
Chat — /rtm/api/runtime/wks/.../conversations, chat-workflow start, chat-session upload (postponed past 5.9.0)
View-based SSE — /api/events/view/{viewId}
Generic SSE other types — CHAT_WORKFLOW_RESPONSE, CHAT_FILE_UPLOAD
Internal runtime endpoints — anything under /rtm/api/runtime-internal/wks/.../app-version/... (including process-resource-id/.../start/test and start/email-trigger)
Languages — /cms/api/languages is not exposed for anonymous in 5.9.0

Error responses

Status	Body `detail`	Cause
403	`Anonymous access not enabled for this application`	The app is not publicly shared (General access is Only invited users and groups).
403	`Anonymous access not enabled for this build`	The build does not carry the Anonymous role on the requested resource.
403	`Anonymous session not found for entity`	The `X-Fx-Anonymous-Session-Id` header does not match the session the entity was created with.
401	`Full authentication is required to access this resource`	The endpoint requires authentication and no bearer token was provided.
401	(any)	A bearer token was sent but invalid or expired. The backend does not fall back to anonymous mode in this case.

CORS requirements

Two headers must be in the gateway’s Access-Control-Allow-Headers allow-list and Access-Control-Expose-Headers response list:

Access-Control-Allow-Headers:
  - X-Fx-Anonymous-Session-Id
  - Fx-BuildId

Access-Control-Expose-Headers:
  - X-Fx-Anonymous-Session-Id

Fx-BuildId is required on SSE connections so the backend can route the stream to the correct build when no user identity is present. The default FlowX commons-security-lib CORS configuration includes both headers from 5.9.0. If you override CORS in your deployment, make sure these are preserved.

Limitations (5.9.0)

Fire-and-forget sessions — closing the browser ends the session. No resumption.
No task assignment to anonymous users. Anonymous can start and act on a process they own via the session ID; they cannot be assigned an existing task.
Mode is locked at renderer init — see Renderer initialization.
No anonymous chat in 5.9.0.
No anonymous languages endpoint (/cms/api/languages).
Subprocesses — data-model-paths calls for subprocesses are gated by the same session-ID check as the root process instance.
Anonymous role cannot be removed or renamed. It can only be added to or removed from a project’s End User Roles.

Swimlanes

Configuring swimlane roles, including Anonymous, for process steps.

Business filters

Other role-driven runtime filtering.

Roles & permissions matrix

Full list of system and end-user roles, with allowed operations.

Web SDK renderer

authToken initialization rules and container-app patterns.

Getting Started

Concepts

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

Resources

API reference

Anonymous runtime access

Overview

The Anonymous role

Make an app publicly accessible

Configure anonymous on a resource

Component visibility for anonymous users

Runtime behaviour scenarios

The anonymous session

Public build, public assets

SDK and container app behaviour

Renderer initialization

Container apps

Platform support

What anonymous users can call

Allowed

Restricted endpoints

Error responses

CORS requirements

Limitations (5.9.0)

Swimlanes

Business filters

Roles & permissions matrix

Web SDK renderer

​Overview

​The Anonymous role

​Make an app publicly accessible

​Configure anonymous on a resource

​Component visibility for anonymous users

​Runtime behaviour scenarios

​The anonymous session

​Public build, public assets

​SDK and container app behaviour

​Renderer initialization

​Container apps

​Platform support

​What anonymous users can call

​Allowed

​Restricted endpoints

​Error responses

​CORS requirements

​Limitations (5.9.0)

​Related resources

Swimlanes

Business filters

Roles & permissions matrix

Web SDK renderer

Overview

The Anonymous role

Make an app publicly accessible

Configure anonymous on a resource

Component visibility for anonymous users

Runtime behaviour scenarios

The anonymous session

Public build, public assets

SDK and container app behaviour

Renderer initialization

Container apps

Platform support

What anonymous users can call

Allowed

Restricted endpoints

Error responses

CORS requirements

Limitations (5.9.0)

Related resources