> ## 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.
# Organization Manager setup
> This guide provides step-by-step instructions for setting up the Organization Manager microservice.
## Dependencies
Before setting up the Organization Manager, ensure you have the following dependencies in place:
* **PostgreSQL** database for storing organization and tenant data
* **Kafka** for event-driven communication with other FlowX.AI services
* **Redis** for caching
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained authorization
## Infrastructure prerequisites
| Component | Description |
| ---------- | ----------------------------------------------------- |
| PostgreSQL | Dedicated database for organization data |
| Kafka | Message broker for inter-service communication |
| Redis | Caching layer for improved performance |
| Keycloak | Identity provider for service authentication |
| SpiceDB | Authorization service for fine-grained access control |
***
## Configuration
### Authorization configuration
| Environment Variable | Description | Default Value |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `SECURITY_TYPE` | Security type (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-organization-manager-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SECURITY_OAUTH2_REALM_ISSUERURIPATTERN` | Per-organization realm URI pattern | `${SECURITY_OAUTH2_BASESERVERURL}/realms/{orgId}` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL (self-reference for security lib) | `http://organization-manager:80` |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT` | Response timeout (in seconds) for HTTP calls from organization-manager to the authorization-system service during organization provisioning. Increase if provisioning calls time out on slow networks. | `60` |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for the same HTTP calls from organization-manager to the authorization-system service during organization provisioning. | `30` |
***
### PostgreSQL configuration
The Organization Manager uses its own dedicated PostgreSQL database.
| Environment Variable | Description | Default Value |
| ---------------------------- | ---------------------------------- | -------------------------------------------------------- |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for PostgreSQL | `jdbc:postgresql://postgresql:5432/organization_manager` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | - |
**PostgreSQL and Redis credentials: plain env vars still work.** Organization Manager is a standard Spring Boot service — it reads the `SPRING_DATASOURCE_*` and `SPRING_DATA_REDIS_*` environment variables shown here. The `postgresql.servers/credentials` and `redis.servers/credentials` blocks in the FlowX Helm chart's `values.yaml` are the chart's own secret-to-env-var mapping; they exist to template the same plain env vars from your secrets. You can keep injecting credentials through plain environment variables exactly as before.
Ensure the database is created before deploying the service. The Organization Manager will manage its own schema migrations via Liquibase.
***
### Redis configuration
Organization Manager uses Redis for caching. Configure Redis connection using the standard Redis environment variables.
**Quick reference:**
| Environment Variable | Description | Example Value | Status |
| ---------------------------- | ----------------------------- | ------------- | --------------- |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |
Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.
For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
***
### Kafka configuration
#### Core Kafka settings
| Environment Variable | Description | Default Value |
| -------------------------------- | ------------------------------ | ------------------ |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS` | Address of the Kafka server(s) | `localhost:9092` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes) | `52428800` (50 MB) |
#### Topic naming configuration
| Environment Variable | Description | Default Value |
| -------------------------------- | ----------------------------------- | ------------- |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |
#### Kafka topics
The Organization Manager publishes organization lifecycle events:
| Environment Variable | Description | Default Value |
| ------------------------------------- | ------------------------------------------------------------------ | --------------------------------- |
| `KAFKA_TOPIC_ORGANIZATION_EVENTS_OUT` | Topic for organization lifecycle events | `ai.flowx.organization.events.v1` |
| `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | Notifies services when LLM provider or model configuration changes | `ai.flowx.llm.config.changed.v1` |
| Environment Variable | Description | Default Value |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `LLM_ENCRYPTION_MASTER_KEY` | Encryption key for LLM provider API keys stored in the database. **Must be changed from the default in production.** | `default-dev-key-change-in-prod` |
Do not use the default encryption key in production. Generate a unique key and keep it consistent across restarts — changing the key after providers are configured will make existing encrypted API keys unreadable.
***
### CAS lib configuration (SpiceDB)
| Environment Variable | Description | Default Value |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `FLOWX_SPICEDB_HOST` | SpiceDB hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB gRPC port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB. Keep the default unless instructed by FlowX. | `CUSTOM` |
***
### Organization ID configuration
The Organization ID is provided by FlowX during the organization registration process. Before starting a deployment or upgrade, this ID must be configured as an environment variable on all FlowX services that run Liquibase migrations.
On self-hosted upgrades (from 5.1 or later), services will not start correctly without the Organization ID. Migration scripts require it to populate the organization ID across all database records.
This is **not needed** for clean installations where no existing data is present in the database.
Set the `ORGANIZATION_ID` Liquibase parameter on the 9 services that backfill `organization_id` columns: `application-manager`, `authorization-system`, `cms-core`, `document-plugin`, `integration-designer`, `notification-plugin`, `organization-manager`, `process-engine`, `scheduler-core`.
```yaml theme={"system"}
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx" # UUID provided by FlowX
```
In self-hosted (non-SaaS) deployments, each of these 9 services **fails to start** if `ORGANIZATION_ID` is missing or not a valid UUID. Set it on all 9 before booting 5.9.x.
For the migrate-vs-fresh-install behavior across the three upgrade scenarios, see the [5.1 → 5.9 organization & deployment configuration guide](/5.9/migrating-from-5.1-lts/organization-deployment#organization_id--where-it-is-actually-required).
***
### Self-hosted URL configuration
Set the Designer and Runtime home URIs to the public URLs clients use to reach each web app. The Organization Manager uses these values to compose Keycloak redirect URIs and email links sent from the platform.
| Environment Variable | Description | Default Value |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| `FLOWX_DEFAULT_DESIGNER_HOME_URI` | Base URL of the Designer web app. Required. | - |
| `FLOWX_DEFAULT_RUNTIME_HOME_URI` | Base URL of the Runtime (generic container) web app. Required when the FlowX generic container app is deployed. | - |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URIS` | Comma-separated list of additional Keycloak redirect URIs. If left empty, the value is derived automatically from `FLOWX_DEFAULT_DESIGNER_HOME_URI` and `FLOWX_DEFAULT_RUNTIME_HOME_URI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]` |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNT_VERIFICATION` | Lifespan of the account verification link sent by email, in seconds. | `172800` (2 days) |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USER_INVITE` | Lifespan of the user invite link sent by email, in seconds. | `172800` (2 days) |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOT_PASSWORD` | Lifespan of the forgot-password link sent by email, in seconds. | `3600` (1 hour) |
In most deployments, setting `FLOWX_DEFAULT_DESIGNER_HOME_URI` (and `FLOWX_DEFAULT_RUNTIME_HOME_URI` when the generic container app is deployed) is enough — leave `FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URIS` empty and the Organization Manager will populate it for you.
#### Designer web app — organization code fallback
Self-hosted deployments must also set the organization code on the **Designer** web app pod. The Designer uses it as a fallback during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present.
| Environment Variable | Description | Default Value | Component |
| --------------------------- | -------------------------------------------------------------------------------------- | ------------- | --------- |
| `DEFAULT_ORGANIZATION_NAME` | Organization code registered with FlowX. Used by the Designer auth flow as a fallback. | - | designer |
Leaving `DEFAULT_ORGANIZATION_NAME` unset on the Designer pod prevents authentication when users access the app at the root URL (no organization in path or subdomain).
***
**License service required.** Self-hosted deployments must also configure the [License service](/5.9/setup-guides/license-engine-setup), which connects to FlowX SaaS for license validation and usage reporting. The Organization Manager publishes organization lifecycle events via Kafka that the License service consumes.
### Self-hosted initialization
When a self-hosted deployment starts for the first time, the Organization Manager provides endpoints for environment setup and organization registration.
#### Environment status endpoint
`GET /org/api/env` (unauthenticated)
Returns the current installation type and status:
| Status | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `ONPREM` + `MISSING_ORGANIZATION` | Organization not yet registered. The setup screen is displayed in Designer. |
| `ONPREM` + `MISSING_LICENCE` | Organization exists but the license has not been synced yet. |
| `ONPREM` + `OK` | Fully configured. Returns organization info (org ID, issuer, token endpoint, client ID, redirect URI). |
#### Organization registration endpoint
`POST /org/api/org/single` (not available on SaaS)
Creates the self-hosted organization using a token provided by FlowX. This endpoint is called from the Designer setup screen and:
* Validates the token against the FlowX SaaS license server
* Creates the organization with the org ID and org code from the token claims
* Creates two Keycloak realms (one for users, one for service accounts)
* Creates the initial org admin user with the credentials provided in the setup screen
For **upgrades from 5.1**, the org admin user already exists and the setup screen is not displayed. The Organization Manager will update the existing Keycloak realm with the new organization ID.
***
### Logging configuration
| Environment Variable | Description | Default Value |
| -------------------- | ------------------------------ | ------------- |
| `LOGGING_LEVEL_ROOT` | Root logging level | `INFO` |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |
***
### Multipart upload configuration
| Environment Variable | Description | Default Value |
| ---------------------------- | ---------------------------- | ------------- |
| `MULTIPART_MAX_FILE_SIZE` | Maximum file size per upload | `50MB` |
| `MULTIPART_MAX_REQUEST_SIZE` | Maximum total request size | `50MB` |
***
## Secrets management
The Organization Manager requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.
| Secret Name | Description |
| ---------------------------------------------------------------------- | ------------------------------- |
| `SPRING_DATASOURCE_PASSWORD` | PostgreSQL database password |
| `SPRING_REDIS_PASSWORD` | Redis authentication password |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token |
***
## Deployment
### Helm values example
Below is an example Helm values configuration for deploying the Organization Manager:
```yaml theme={"system"}
fullnameOverride: organization-manager
image:
repository: /organization-manager
replicaCount: 1
env:
SPRING_PROFILES_ACTIVE: production
# PostgreSQL
SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/organization_manager
SPRING_DATASOURCE_USERNAME: postgres
# Kafka
SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092
# Security
SECURITY_TYPE: jwt-public-key
SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth
SECURITY_OAUTH2_SAREALM: 00000002-0002-4002-8002-000000000002
# Redis
SPRING_REDIS_HOST: redis-master
# SpiceDB
FLOWX_SPICEDB_HOST: spicedb
FLOWX_SPICEDB_PORT: 50051
# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
- name: postgresql-generic
secrets:
SPRING_DATASOURCE_PASSWORD: postgresql-password-key
- name: redis-generic
secrets:
SPRING_REDIS_PASSWORD: redis-password
- name: flowx-auth
secrets:
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakOrgManagerClientSecret
- name: spicedb-generic
secrets:
FLOWX_SPICEDB_TOKEN: spicedb-token
rbac:
create: true
ingress:
enabled: false
podLabels:
flowx.ai/network-log: "true"
flowx.ai/egress-s-kafka: "true"
flowx.ai/egress-s-postgresql: "true"
flowx.ai/routing-name: "organization-manager"
flowx.ai/prometheus-scrape: "organization-manager"
```
### Network policies
The Organization Manager requires network access to the following services:
| Service | Purpose | Pod Label |
| ---------- | ---------------------------- | ------------------------------ |
| Kafka | Message broker communication | `flowx.ai/egress-s-kafka` |
| PostgreSQL | Primary data storage | `flowx.ai/egress-s-postgresql` |
| Redis | Caching | `flowx.ai/egress-s-redis` |
| Keycloak | Authentication | `flowx.ai/egress-s-keycloak` |
| SpiceDB | Authorization | `flowx.ai/egress-s-spicedb` |
***
## Monitoring
The Organization Manager exposes Prometheus metrics for monitoring. Turn on scraping by setting the pod label:
```yaml theme={"system"}
podLabels:
flowx.ai/prometheus-scrape: "organization-manager"
```
### Health endpoints
| Endpoint | Description |
| ------------------- | --------------------------- |
| `/actuator/health` | Health check endpoint |
| `/actuator/metrics` | Prometheus metrics endpoint |
| `/actuator/info` | App info endpoint |
***
## Verify your setup
The Organization Manager pod is running and healthy: `kubectl get pods -l app=organization-manager`
The health endpoint returns HTTP 200: `curl http://organization-manager:8080/actuator/health`
Database migrations completed successfully — check pod logs for `Liquibase: Update has been successful`
SpiceDB connection is established — check pod logs for successful CAS client initialization
Kafka topic `ai.flowx.organization.events.v1` exists and the service can publish to it
***
## Ingress and CORS
The Organization Manager service is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.
### Service routes
| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin | `/org` | `/` |
| public | `/org` | `/` |
Paths are set through `services.organization-manager.ingress.admin.path` / `services.organization-manager.ingress.public.path` (or the corresponding `gateway..paths`) in the chart values.
### CORS configuration
| Environment Variable | Description | Default Value |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `APPLICATION_CORS_ALLOW_ORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Organization Manager. | `-` |
Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.
For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).
***
## Troubleshooting
**Symptoms:** Service fails to start with database connection errors.
**Solutions:**
1. Verify the `organization_manager` database exists in PostgreSQL
2. Check that the database user has appropriate permissions
3. Ensure network connectivity between the pod and PostgreSQL service
4. Verify the JDBC URL format is correct
**Symptoms:** Authorization errors or service fails to initialize CAS client.
**Solutions:**
1. Verify SpiceDB is running and reachable at the configured host and port
2. Check that the SpiceDB token is correct
3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`
4. Review pod logs for specific CAS client error messages
**Symptoms:** Organization events not reaching downstream services.
**Solutions:**
1. Verify Kafka bootstrap servers are reachable
2. Check that the `ai.flowx.organization.events.v1` topic exists
3. Ensure the service has producer permissions on the topic
4. Review `KAFKA_MESSAGE_MAX_BYTES` if large messages fail
**Symptoms:** 401/403 errors when communicating with other FlowX services.
**Solutions:**
1. Verify the Keycloak service account is properly configured
2. Check that client secrets match between configuration and Keycloak
3. Ensure the service account has required roles assigned
4. Verify `SECURITY_TYPE` is set to `jwt-public-key`
***
## Related resources
Complete Redis setup including Sentinel and Cluster modes
Configure roles and access rights
Fine-grained authorization setup
Identity and access management setup