> ## 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.

# Overview

> Migration guide for upgrading from FlowX.AI v5.4.0 to v5.5.0

<Warning>
  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.
</Warning>

## 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

<Warning>
  **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.
</Warning>

## Migration process

<Steps>
  <Step title="Back up your configuration">
    Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.
  </Step>

  <Step title="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](#update-keycloak-service-accounts) for the full mapping.
  </Step>

  <Step title="Update environment variables">
    Remove deprecated variables and update changed defaults. See [Update environment variables](./update-environment-variables-5.5) for a per-service breakdown.
  </Step>

  <Step title="Deploy Organization Manager">
    If applicable, deploy the new Organization Manager microservice. See the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup) for infrastructure requirements.
  </Step>

  <Step title="Deploy and verify">
    Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.
  </Step>
</Steps>

***

## 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**.

<Info>
  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.
</Info>

### Removed environment variables

The following environment variables have been removed and are no longer supported:

| Environment Variable                                                    | Description                                  | Previously Used By |
| ----------------------------------------------------------------------- | -------------------------------------------- | ------------------ |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint          | 14 services        |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID`         | Client ID for opaque-token introspection     | 14 services        |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET`     | Client secret for opaque-token introspection | 14 services        |
| `SECURITY_OAUTH2_REALM`                                                 | OAuth2 realm name                            | 13 services        |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID`                                      | OAuth2 client ID                             | 13 services        |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`                                  | OAuth2 client secret                         | 13 services        |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID`                       | Service account admin client ID              | 8 services         |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET`                   | Service account admin client secret          | 8 services         |

### Changed default values

| Environment Variable                                                    | Old Default                                              | New Default                           | Affected Services |
| ----------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------- | ----------------- |
| `SECURITY_TYPE`                                                         | `oauth2`                                                 | `jwt-public-key`                      | 14/19 services    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID`     | `${security.oauth2.service-account.admin.client-id}`     | `flowx-${spring.application.name}-sa` | 8 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_URI`     | Uses `${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:

| Service                | New Client ID                     |
| ---------------------- | --------------------------------- |
| Admin                  | `flowx-admin-sa`                  |
| Process Engine         | `flowx-process-engine-sa`         |
| Integration Designer   | `flowx-integration-designer-sa`   |
| Authorization System   | `flowx-authorization-system-sa`   |
| Runtime Manager        | `flowx-runtime-manager-sa`        |
| Scheduler Core         | `flowx-scheduler-core-sa`         |
| Task Management Plugin | `flowx-task-management-plugin-sa` |
| Organization Manager   | `flowx-organization-manager-sa`   |
| License                | `flowx-license-sa`                |
| Email Gateway          | `flowx-email-gateway-sa`          |

<Warning>
  Ensure you update both the Keycloak client IDs **and** the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.
</Warning>

***

## 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](/5.1/setup-guides/organization-manager-setup).

***

## Backward compatibility

<Warning>
  **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.
</Warning>

## 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

<Info>
  Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.
</Info>

***

## Additional resources

<CardGroup cols={2}>
  <Card title="Update Environment Variables" href="./update-environment-variables-5.5" icon="list-check">
    Per-service environment variable changes for v5.5.0
  </Card>

  <Card title="Deployment Guidelines v5.5.0" href="../deployment-guidelines-v5.5" icon="rocket">
    Component versions and deployment instructions
  </Card>

  <Card title="IAM Configuration" href="/5.1/setup-guides/access-management/configuring-an-iam-solution" icon="key">
    Keycloak setup and service account configuration
  </Card>

  <Card title="Release Notes v5.5.0" href="../v5.5.0-february-2026" icon="file-lines">
    Full release notes for v5.5.0
  </Card>
</CardGroup>

## Support

<Info>
  For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.
</Info>