Skip to main content
FlowX.AI v5.5.0 introduces a critical breaking change to the default authentication mechanism across 14 of 19 platform services. Action is required before upgrading.

​
What’s changing

FlowX.AI v5.5.0 changes the default authentication mechanism from opaque-token introspection (oauth2) to JWT-based authentication (jwt-public-key). This affects service-to-service communication, service account configuration in Keycloak, and multiple environment variables across the platform. Additionally, a new microservice — Organization Manager — has been introduced for organization and tenant management.

​
Who is affected

All deployments are affected by the authentication mechanism change. The default SECURITY_TYPE value has changed from oauth2 to jwt-public-key across 14 of 19 platform services.If you explicitly set SECURITY_TYPE=oauth2 or rely on opaque-token introspection, you must update your configuration before upgrading.

​
Migration process

1

Back up your configuration

Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.
2

Update Keycloak service accounts

Update your Keycloak service account client IDs to follow the new flowx-{service-name}-sa naming pattern. See Update Keycloak service accounts for the full mapping.
3

Update environment variables

Remove deprecated variables and update changed defaults. See Update environment variables for a per-service breakdown.
4

Deploy Organization Manager

If applicable, deploy the new Organization Manager microservice. See the Organization Manager Setup Guide for infrastructure requirements.
5

Deploy and verify

Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.

​
Authentication mechanism change

​
Overview

The default value of SECURITY_TYPE has changed from oauth2 to jwt-public-key across 14 of 19 platform services. Opaque-token introspection has been removed entirely.
A new security.oauth2.sa-realm property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

​
Removed environment variables

The following environment variables have been removed and are no longer supported:
Environment VariableDescriptionPreviously Used By
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URIOpaque-token introspection endpoint14 services
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_IDClient ID for opaque-token introspection14 services
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRETClient secret for opaque-token introspection14 services
SECURITY_OAUTH2_REALMOAuth2 realm name13 services
SECURITY_OAUTH2_CLIENT_CLIENT_IDOAuth2 client ID13 services
SECURITY_OAUTH2_CLIENT_CLIENT_SECRETOAuth2 client secret13 services
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_IDService account admin client ID8 services
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETService account admin client secret8 services

​
Changed default values

Environment VariableOld DefaultNew DefaultAffected Services
SECURITY_TYPEoauth2jwt-public-key14/19 services
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID${security.oauth2.service-account.admin.client-id}flowx-${spring.application.name}-sa8 services
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET${security.oauth2.service-account.admin.client-secret}-8 services
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URIUses ${security.oauth2.realm}Uses ${security.oauth2.sa-realm}8 services

​
Update Keycloak service accounts

Service account client IDs now follow the flowx-{service-name}-sa pattern. Update your Keycloak configuration to match:
ServiceNew Client ID
Adminflowx-admin-sa
Process Engineflowx-process-engine-sa
Integration Designerflowx-integration-designer-sa
Authorization Systemflowx-authorization-system-sa
Runtime Managerflowx-runtime-manager-sa
Scheduler Coreflowx-scheduler-core-sa
Task Management Pluginflowx-task-management-plugin-sa
Organization Managerflowx-organization-manager-sa
Licenseflowx-license-sa
Email Gatewayflowx-email-gateway-sa
Ensure you update both the Keycloak client IDs and the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.

​
New microservice: Organization Manager

FlowX.AI 5.5.0 introduces the Organization Manager microservice for organization and tenant management, user registration, and platform component health monitoring. Infrastructure requirements:
  • PostgreSQL
  • Redis
  • Kafka
  • Keycloak/IAM
  • SpiceDB
For full setup instructions, see the Organization Manager Setup Guide.

​
Backward compatibility

No backward compatibility for the authentication mechanism change. The opaque-token introspection mechanism has been removed entirely. You must update your configuration before or immediately after upgrading to v5.5.0.

​
Rollback support

If you need to rollback from v5.5.0 to v5.4.x:
  1. Revert your SECURITY_TYPE and environment variables to the previous configuration
  2. Restore the previous Keycloak service account client IDs
  3. Re-add the removed opaque-token variables if they were in use
  4. Downgrade all platform service containers to their v5.4.x versions
Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.

​
Additional resources

Update Environment Variables

Per-service environment variable changes for v5.5.0

Deployment Guidelines v5.5.0

Component versions and deployment instructions

IAM Configuration

Keycloak setup and service account configuration

Release Notes v5.5.0

Full release notes for v5.5.0

​
Support

For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.
Last modified on February 27, 2026