Documentation Index
Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
Use this file to discover all available pages before exploring further.
Available starting with FlowX.AI 5.8.0 Runtime authorization replaces the previous model of assigning roles directly to users with a project-scoped model: roles are defined at the organization level, listed on each project version, and assigned to users or end-user groups when a solution is shared from the Solutions page.
Overview
Up to FlowX.AI 5.7.0, an end-user role granted access to every project and workspace where that role appeared. Champions deploying to enterprise customers (OTP, ProCredit, Triglav) needed finer granularity: “this role on this solution, not on every other solution that happens to use the same role name.” Runtime authorization changes the assignment model. The role itself is still organization-level (defined once, reusable across projects). What’s new is where the role is granted: on a specific project, through the Share modal on a solution.| 5.7.0 | 5.8.0+ |
|---|---|
| Role assigned directly to user at organization level | Role assigned to user in the context of a project via the solution’s Share modal |
| One role grants access on every project that lists it | Role grants access only on the solutions it has been explicitly shared on |
| End-user groups managed in Keycloak | End-user groups managed in FlowX (org-level), assigned to roles on each solution |
Where roles live
Organization
The role catalog. Roles are created and named once per organization and reusable across all projects and libraries.
Project version (build)
Each project version carries the list of roles required at runtime. New projects spawn with a default
user role.Per resource
On process swimlanes: which role(s) can view, execute, or self-assign tasks. On UI Flows: which role(s) can interact (UI Flows have a single “interact” permission).
Designer-time vs runtime permissions. FlowX uses SpiceDB for designer-time (build-time) permissions — who can edit which resource in the Designer. Runtime permissions are a separate, custom implementation; SpiceDB does not handle runtime checks because the volume of runtime permission evaluations made the SpiceDB latency unacceptable. Both systems coexist and don’t interact at runtime.
Sharing a solution
A solution becomes accessible to end users through the Share modal on the Solutions page in the generic container app.Open the Solutions page
In the generic container app, open Solutions. Each card represents a runtime application backed by a project version.
Open the Share modal
On the solution you want to share, click Share. The modal shows the roles that the project version exposes at runtime, plus the search inputs for users and groups.
Pick a user or group, then a role
Type a name to search. Existing FlowX users appear in the dropdown; you can also invite a brand-new user from the same modal — the user receives a Keycloak invitation email.Assign one role per user or group. Repeat per role to give the same user multiple roles.
End-user groups
Groups previously managed in Keycloak are now managed inside FlowX. Each group is a named bucket of users; you assign the group to a role on a solution rather than assigning the role to each user individually. Manage groups under Organization Settings → Access Management → End-User Groups. See End-user access management for the org-level group lifecycle (create, archive, search).End-user groups page
The End-User Groups list shows every group in the organization with a Members column for the current member count, so it’s easy to scan a long list. Click a group to open its detail page, which has two tabs:Members
The list of end users in the group. Use the Add Members action to attach users (search by name or email) and remove members inline. Saving updates the group membership immediately; the next sign-in for those users picks up any solution access changes.
Solution access
The list of solutions the group is granted on, plus the role it carries on each. Click Add Solution Access, pick a solution, and pick the role to grant. The Active Policy of the chosen solution determines which roles appear in the role dropdown.
Two ways to grant access
Sharing a solution with an end-user group can be done from either side; the resulting permission is the same.| From | When to use |
|---|---|
| Solutions page → Share modal on a solution | When you want to set up everyone who can use a single solution in one place — typical for app owners reviewing a deployment. |
| End-User Groups → group → Solution access tab | When you want to set up everything a single group can reach — typical for onboarding a new cohort or an end-user group that spans multiple solutions. |
Solutions with multiple roles. When a project version exposes more than one runtime role (for example
user and supervisor), both Share modal entries and Solution access entries let you pick which role to grant to the user or group. Repeat the entry to grant the same group multiple roles on the same solution.Recommended patterns
Single-role solution
Create one All End Users group, give it the
user role on the solution. Add new end users to the group as they onboard.Multi-role solution
Create one group per role on the solution. Add users to the group that matches the access they need. Reuse groups across solutions when the same cohort needs the same access on more than one app.
Designer-user bypass
A user with Designer access to a project can run that project at runtime without being assigned any runtime role on it.- Auto-grants view, execute, and self-assign on every swimlane in the project.
- The bypass is explicit on purpose: it lets a project’s designers run their own work while building, without filing themselves into the runtime role catalog.
- Designer users cannot test scenarios “as another runtime role.” To verify role-specific behavior, create a test end-user, assign the role to that user via the Share modal, and sign in as that user.
designerUser Keycloak user attribute (boolean) auto-managed at organization provisioning. It is exposed on the access token as the attributes.designerUser claim so the engine can decide cheaply whether to apply runtime checks. For environments that block FlowX from administering Keycloak directly, the mapper recipe is in Configuring an IAM solution → Designer user attribute.
What stays in Keycloak vs FlowX
| Concern | System of record |
|---|---|
| Authentication, password policy, MFA | Keycloak |
| User attributes used by business filters | Keycloak |
| Federation with external IDPs | Keycloak |
| Runtime role catalog | FlowX |
| End-user groups | FlowX |
| Project-scoped role assignment (sharing) | FlowX |
Per-organization IDP federation
Enterprise customers typically own their identity provider (Microsoft Entra ID, Okta, Keycloak in another tenancy, AD FS). Rather than managing those users a second time inside FlowX, you can federate the customer’s IDP into the FlowX Keycloak realm for that organization, so end users sign in with their existing IDP credentials and FlowX picks up their group memberships automatically. The contract between the federated IDP and FlowX is a set of namespaced claims underattributes.* on the FlowX-issued access token. FlowX-specific user data — group memberships, business-filter values, the designer-user flag — all flow through this attributes object so that downstream services have a single, predictable read path.
Token-claim contract
The FlowX access token carries the following claims under the top-levelattributes object:
| Claim | Type | Required | What it carries |
|---|---|---|---|
attributes.runtimeGroups | multivalued string | yes (for federated logins) | List of FlowX end-user group names the user belongs to. The names must match groups defined under Organization Settings → Access Management → End-User Groups. |
attributes.businessFilters | multivalued string | only if the org uses business filters | Values of business-filter attributes for the user. See Business filters for how filter values gate which records a runtime user can act on. |
attributes.designerUser | boolean | always present | true when the user has Designer access to the project; FlowX uses this to apply the designer-user bypass. |
org_id | string | always present | The organization realm UUID. Hardcoded by Keycloak at organization provisioning. |
Behind these claims, on the Keycloak user record: the
attributes.runtimeGroups claim is fed by a user attribute named flowxIdPGroups; attributes.businessFilters is fed by businessFilter; attributes.designerUser is fed by designerUser. Federated logins populate these user attributes automatically through IDP mappers; manual Keycloak setups can write them directly.How the sync runs
The federation chain is wired with three Keycloak mappers per attribute. Group memberships are the canonical example:- Source IDP claim emitter. The customer’s IDP issues a token containing whatever attribute they maintain — commonly
memberOf,groups,roles, or a vendor-specific path. - IDP-to-user-attribute mapper (on the federated IDP instance inside the FlowX Keycloak realm). Reads the source claim and writes its value into the
flowxIdPGroupsuser attribute on the FlowX-side Keycloak user record. In the demo configuration the source claim isgroupsList, but the source name is customer-specific — you only need to make sure this mapper writes toflowxIdPGroups. - User-attribute-to-token-claim mapper (on the
flowx-platform-authenticateclient). ReadsflowxIdPGroupsfrom the user record and adds it to the access token asattributes.runtimeGroups(multivalued, aggregated). This mapper is part of the standard FlowX client setup; you should not need to touch it.
businessFilter user attribute → attributes.businessFilters token claim. The first and last steps are FlowX-managed; only the middle “IDP-to-user-attribute” mapper needs per-customer configuration.
On the first permission check after sign-in, FlowX reads attributes.runtimeGroups from the token, looks up the matching FlowX end-user groups, and writes the user’s membership rows into FlowX’s group_membership table. Subsequent permission checks read from that table directly.
Lazy sync, not push. FlowX does not poll the source IDP and does not implement SCIM. A change to a user’s groups in the source IDP only propagates after the user’s current FlowX access token expires and they sign in again. Plan token lifetimes accordingly: very long lifetimes mask group changes, very short lifetimes increase auth overhead.
Migration notes
If you upgrade from 5.7.0 with existing role-on-user assignments, those assignments continue to work. New solutions and new role assignments use the project-scoped model. End-user groups managed in Keycloak before 5.8.0 are not automatically migrated into FlowX-managed groups; recreate them inside End-Users Groups.Related resources
End-user access management
Org-level end-user, role, and group management
Workspaces access rights
Designer-side access to workspaces and projects
Roles & permissions matrix
Full matrix of designer and end-user roles
Configuring access roles for processes
Per-swimlane role configuration on process definitions