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

# FlowX Admin setup

> Complete configuration reference for the FlowX Admin microservice, including logging, databases, Kafka, and various subsystems.

This guide provides a comprehensive reference for configuring the FlowX Admin microservice using environment variables and configuration files.

## Infrastructure prerequisites

Before setting up the Admin microservice, ensure the following components are properly set up:

* **Database Instance**: The Admin microservice connects to the same database as the FlowX.AI Engine.
* **MongoDB**: For additional data management.
* **Redis**: For caching and transient data storage.
* **Kafka**: For audit logs, events, and messaging (if using FlowX.AI Audit functionality).

***

## Core configuration

### Server configuration

| Environment Variable                        | Description                                        | Default Value |
| ------------------------------------------- | -------------------------------------------------- | ------------- |
| `SERVER_PORT`                               | Port on which the Admin service will run           | `8080`        |
| `SPRING_APPLICATION_NAME`                   | Name of the application used for service discovery | `admin`       |
| `SPRING_JACKSON_SERIALIZATION_INDENTOUTPUT` | Enable indented JSON output                        | `true`        |

***

## Database configuration

The Admin microservice connects to the same PostgreSQL or Oracle database as the FlowX.AI Engine for storing process definitions.

| Environment Variable         | Description                      | Default Value                            |
| ---------------------------- | -------------------------------- | ---------------------------------------- |
| `SPRING_DATASOURCE_URL`      | JDBC URL for database connection | `jdbc:postgresql://localhost:5432/flowx` |
| `SPRING_DATASOURCE_USERNAME` | Database username                | `postgres`                               |
| `SPRING_DATASOURCE_PASSWORD` | Database password                | `[your-secure-password]`                 |

<Warning>
  You will need to make sure that the user, password, connection link and database name are configured correctly, otherwise, you will receive errors at start time.
</Warning>

<Info>
  The database schema is managed by a [Liquibase](https://www.liquibase.org/) script provided with the Engine.
</Info>

***

## MongoDB configuration

The Admin microservice also connects to a MongoDB database instance for additional data management.

| Environment Variable                     | Description                                | Default Value                                                                         |
| ---------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
| `DB_USERNAME`                            | MongoDB username                           | `data-model`                                                                          |
| `DB_PASSWORD`                            | MongoDB password                           | `[your-secure-password]`                                                              |
| `DB_NAME`                                | MongoDB database name                      | `data-model`                                                                          |
| `SPRING_DATA_MONGODB_URI`                | MongoDB connection URI                     | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@localhost:27017/${DB_NAME}?retryWrites=true` |
| `SPRING_DATA_MONGODB_UUIDREPRESENTATION` | UUID representation format                 | `standard`                                                                            |
| `SPRING_DATA_MONGODB_STORAGE`            | Storage type (Azure environments)          | `mongodb` or `cosmosdb`                                                               |
| `MONGOCK_CHANGELOGSSCANPACKAGE_0_`       | Mongock changelog scan package             | `ai.flowx.admin.data.model.config.mongock`                                            |
| `MONGOCK_TRANSACTIONENABLED`             | Enable transactions for Mongock operations | `false`                                                                               |

<Info>
  Ensure that the MongoDB configuration is compatible with the same database requirements as the FlowX.AI Engine, especially if sharing database instances.
</Info>

***

## Redis and caching configuration

Admin Service uses Redis for caching and storing transient data. 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        |

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

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

***

## Kafka configuration

The Admin microservice uses Kafka for sending audit logs, managing scheduled timer events, platform component versions, and start timer event updates.

### General Kafka settings

| Environment Variable             | Description                   | Default Value     |
| -------------------------------- | ----------------------------- | ----------------- |
| `SPRING_KAFKA_BOOTSTRAPSERVERS`  | Kafka broker addresses        | `localhost:9092`  |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol             | `PLAINTEXT`       |
| `KAFKA_MESSAGE_MAX_BYTES`        | Maximum message size in bytes | `52428800` (50MB) |

### Kafka producer configuration

| Environment Variable                    | Description            | Default Value                                                 |
| --------------------------------------- | ---------------------- | ------------------------------------------------------------- |
| `SPRING_KAFKA_PRODUCER_KEYSERIALIZER`   | Key serializer class   | `org.apache.kafka.common.serialization.StringSerializer`      |
| `SPRING_KAFKA_PRODUCER_VALUESERIALIZER` | Value serializer class | `org.springframework.kafka.support.serializer.JsonSerializer` |
| `SPRING_KAFKA_PRODUCER_MAXREQUESTSIZE`  | Maximum request size   | `52428800` (50MB)                                             |

### Kafka consumer configuration

| Environment Variable                                        | Description                                             | Default Value                                  |
| ----------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------- |
| `KAFKA_CONSUMER_GROUPID_GENERICPROCESSING`                  | Generic processing consumer group                       | `generic-processing-group`                     |
| `KAFKA_CONSUMER_THREADS_GENERICPROCESSING`                  | Generic processing threads                              | `6`                                            |
| `KAFKA_CONSUMER_GROUPID_PROCESSSYNC`                        | Process sync consumer group                             | `process-sync-group`                           |
| `KAFKA_CONSUMER_THREADS_PROCESSSYNC`                        | Process sync consumer threads                           | `6`                                            |
| `KAFKA_CONSUMER_GROUPID_BUSINESSRULESYNC`                   | Business rule sync consumer group                       | `business-rule-sync-group`                     |
| `KAFKA_CONSUMER_THREADS_BUSINESSRULESYNC`                   | Business rule sync consumer threads                     | `6`                                            |
| `KAFKA_CONSUMER_GROUPID_REUSABLETEMPLATESYNC`               | Reusable template sync consumer group                   | `reusable-template-sync-group`                 |
| `KAFKA_CONSUMER_THREADS_REUSABLETEMPLATESYNC`               | Reusable template sync consumer threads                 | `6`                                            |
| `KAFKA_CONSUMER_GROUPID_UIFLOWSYNC`                         | UI flow sync consumer group                             | `ui-flow-sync-group`                           |
| `KAFKA_CONSUMER_THREADS_UIFLOWSYNC`                         | UI flow sync consumer threads                           | `6`                                            |
| `KAFKA_CONSUMER_GROUPID_PROCESSCORRECTIONAFTERAPPOPERATION` | Process correction after app operation consumer group   | `process-correction-after-app-operation-group` |
| `KAFKA_CONSUMER_THREADS_PROCESSCORRECTIONAFTERAPPOPERATION` | Process correction after app operation consumer threads | `6`                                            |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL`                          | Auth exception retry interval (seconds)                 | `10`                                           |

### Topic naming configuration

| Environment Variable             | Description                          | Default Value                                                    |
| -------------------------------- | ------------------------------------ | ---------------------------------------------------------------- |
| `DOT`                            | Reference to the primary separator   | `${kafka.topic.naming.separator}`                                |
| `DASH`                           | Reference to the secondary separator | `${kafka.topic.naming.separator2}`                               |
| `KAFKA_TOPIC_NAMING_PACKAGE`     | Base package name                    | `ai${dot}flowx${dot}`                                            |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment name                     | ` `                                                              |
| `KAFKA_TOPIC_NAMING_VERSION`     | Topic version                        | `${dot}v1`                                                       |
| `KAFKA_TOPIC_NAMING_SEPARATOR`   | Primary separator                    | `.`                                                              |
| `KAFKA_TOPIC_NAMING_SEPARATOR2`  | Secondary separator                  | `-`                                                              |
| `KAFKA_TOPIC_NAMING_PREFIX`      | Combined prefix                      | `${kafka.topic.naming.package}${kafka.topic.naming.environment}` |
| `KAFKA_TOPIC_NAMING_SUFFIX`      | Combined suffix                      | `${kafka.topic.naming.version}`                                  |

### Kafka topics configuration

#### Application topics

| Environment Variable                                                      | Description                                        | Pattern                                                                                                                                | Default Value                                                                              |
| ------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `KAFKA_TOPIC_APPLICATION_SYNCRESPONSE`                                    | Sync response topic                                | `${kafka.topic.naming.prefix}application-version.sync.out${kafka.topic.naming.suffix}`                                                 | `ai.flowx.application-version.sync.out.v1`                                                 |
| `KAFKA_TOPIC_APPLICATION_PROCESSSYNC`                                     | Process sync topic                                 | `${kafka.topic.naming.prefix}application-version.sync.process.in${kafka.topic.naming.suffix}`                                          | `ai.flowx.application-version.sync.process.in.v1`                                          |
| `KAFKA_TOPIC_APPLICATION_BUSINESSRULESYNC`                                | Business rule sync topic                           | `${kafka.topic.naming.prefix}application-version.sync.business-rule.in${kafka.topic.naming.suffix}`                                    | `ai.flowx.application-version.sync.business-rule.in.v1`                                    |
| `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATESYNC`                            | Reusable template sync topic                       | `${kafka.topic.naming.prefix}application-version.sync.reusable-template.in${kafka.topic.naming.suffix}`                                | `ai.flowx.application-version.sync.reusable-template.in.v1`                                |
| `KAFKA_TOPIC_APPLICATION_RESOURCEUPDATEPROPAGATION`                       | Resource update propagation topic                  | `${kafka.topic.naming.prefix}application-version.resource.update.propagation${kafka.topic.naming.suffix}`                              | `ai.flowx.application-version.resource.update.propagation.v1`                              |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS`          | Correction after app operation → process request   | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.process.request${kafka.topic.naming.suffix}`           | `ai.flowx.application-version.correction-after-app-operation.process.request.v1`           |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE`     | Correction after app operation → business rule     | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.business-rule.request${kafka.topic.naming.suffix}`     | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1`     |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | Correction after app operation → reusable template | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.reusable-template.request${kafka.topic.naming.suffix}` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_UIFLOW`           | Correction after app operation → UI flow           | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.ui-flow.request${kafka.topic.naming.suffix}`           | `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1`           |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT`                 | Correction after app operation response topic      | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.response${kafka.topic.naming.suffix}`                  | `ai.flowx.application-version.correction-after-app-operation.response.v1`                  |
| `KAFKA_TOPIC_APPLICATION_UIFLOWSYNC`                                      | UI flow sync topic                                 | `${kafka.topic.naming.prefix}application-version.sync.ui-flow.in${kafka.topic.naming.suffix}`                                          | `ai.flowx.application-version.sync.ui-flow.in.v1`                                          |

#### Audit topics

| Environment Variable    | Description        | Pattern                                                                                          | Default Value                         |
| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------- |
| `KAFKA_TOPIC_AUDIT_OUT` | Audit output topic | `${kafka.topic.naming.prefix}core${dot}trigger${dot}save${dot}audit${kafka.topic.naming.suffix}` | `ai.flowx.core.trigger.save.audit.v1` |

#### Platform Topics

| Environment Variable                         | Description                       | Pattern                                                                                                              | Default Value                                        |
| -------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `KAFKA_TOPIC_PLATFORM_COMPONENTSVERSIONS_IN` | Components versions caching topic | `${kafka.topic.naming.prefix}core${dot}trigger${dot}platform${dot}versions${dot}caching${kafka.topic.naming.suffix}` | `ai.flowx.core.trigger.platform.versions.caching.v1` |

#### Events gateway topics

| Environment Variable                    | Description                   | Pattern                                                                                                         | Default Value                                        |
| --------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Commands message output topic | `${kafka.topic.naming.prefix}eventsgateway${dot}process${dot}commands${dot}message${kafka.topic.naming.suffix}` | `ai.flowx.eventsgateway.process.commands.message.v1` |

#### Build topics

| Environment Variable                             | Description                      | Pattern                                                                                                                  | Default Value                                     |
| ------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA`                  | Build runtime data topic         | `${kafka.topic.naming.prefix}build${dot}runtime-data${kafka.topic.naming.suffix}`                                        | `ai.flowx.build.runtime-data.v1`                  |
| `KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_OUT_UPDATES` | Start timer events updates topic | `${kafka.topic.naming.prefix}build${dot}start${dash}timer${dash}events${dot}updates${dot}in${kafka.topic.naming.suffix}` | `ai.flowx.build.start-timer-events.updates.in.v1` |

#### Resource topics

| Environment Variable                  | Description                    | Pattern                                                                                                                      | Default Value                                              |
| ------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH` | Resources usages refresh topic | `${kafka.topic.naming.prefix}application${dash}version${dot}resources${dash}usages${dot}refresh${kafka.topic.naming.suffix}` | `ai.flowx.application-version.resources-usages.refresh.v1` |

### OAuth authentication for Kafka

When using the `kafka-auth` profile, the following variables configure OAuth for Kafka:

| Environment Variable             | Description          | Default Value          |
| -------------------------------- | -------------------- | ---------------------- |
| `KAFKA_OAUTH_CLIENT_ID`          | OAuth client ID      | `kafka`                |
| `KAFKA_OAUTH_CLIENT_SECRET`      | OAuth client secret  | `kafka-secret`         |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

<Info>
  When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.
</Info>

***

## CAS lib configuration

| Environment Variable  | Description                  | Default Value   |
| --------------------- | ---------------------------- | --------------- |
| `FLOWX_SPICEDB_HOST`  | SpiceDB server hostname      | `spicedb`       |
| `FLOWX_SPICEDB_PORT`  | SpiceDB server port          | `50051`         |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `spicedb-token` |

***

## Logging configuration

The FlowX Admin microservice provides granular control over logging levels for different components:

| Environment Variable | Description                                 | Default Value |   |
| -------------------- | ------------------------------------------- | ------------- | - |
| `LOGGING_LEVEL_ROOT` | Log level for root Spring Boot microservice | `INFO`        |   |
| `LOGGING_LEVEL_APP`  | Log level for application-specific code     | `DEBUG`       |   |

### Changing log levels at runtime

You can adjust log levels dynamically without restarting the service using Spring Boot Actuator endpoints. This is particularly useful for troubleshooting and debugging in production environments.

**Example: Change log level for a specific package**

```bash theme={"system"}
curl 'http://localhost:8081/actuator/loggers/ai.flowx.admin' \
  -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel":"DEBUG"}'
```

**Common logger packages:**

* `ai.flowx.admin` - Application-specific logs
* `org.springframework` - Spring Framework logs
* `org.mongodb.driver` - MongoDB driver logs
* `org.apache.kafka` - Kafka client logs

**Available log levels:**

`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`

<Warning>
  Using `DEBUG` or `TRACE` log levels in production may impact performance and generate large log volumes. Revert to `INFO` or `WARN` after troubleshooting is complete.
</Warning>

***

## Localization settings

| Environment Variable           | Description                        | Default Value |
| ------------------------------ | ---------------------------------- | ------------- |
| `APPLICATION_DEFAULTLOCALE`    | Default locale for the application | `en`          |
| `APPLICATION_SUPPORTEDLOCALES` | List of supported locales          | `en, ro`      |

***

## Health monitoring

| Environment Variable                           | Description                              | Default Value                           |
| ---------------------------------------------- | ---------------------------------------- | --------------------------------------- |
| `MANAGEMENT_HEALTH_DB_ENABLED`                 | Enable database health checks            | `true`                                  |
| `MANAGEMENT_HEALTH_KAFKA_ENABLED`              | Enable Kafka health checks               | `true`                                  |
| `MANAGEMENT_SERVER_ADDRESS`                    | Management server bind address           | `0.0.0.0`                               |
| `MANAGEMENT_SERVER_PORT`                       | Management server port                   | `8081`                                  |
| `MANAGEMENT_SERVER_BASEPATH`                   | Base path for management endpoints       | `/manage`                               |
| `MANAGEMENT_SECURITY_ENABLED`                  | Enable security for management endpoints | `false`                                 |
| `MANAGEMENT_ENDPOINTS_WEB_BASEPATH`            | Base path for actuator endpoints         | `/actuator`                             |
| `MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE`    | Endpoints to expose                      | `health,info,metrics,metric,prometheus` |
| `MANAGEMENT_ENDPOINT_HEALTH_PROBES_ENABLED`    | Enable Kubernetes probes                 | `true`                                  |
| `MANAGEMENT_ENDPOINT_HEALTH_SHOWDETAILS`       | Show health check details                | `always`                                |
| `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED` | Enable Prometheus metrics export         | `false`                                 |

### Platform health configuration

| Environment Variable                         | Description                                                                 | Default Value                           |
| -------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------- |
| `FLOWX_PLATFORMHEALTH_NAMESPACE`             | Kubernetes namespace for health checks                                      | `flowx`                                 |
| `FLOWX_PLATFORMHEALTH_MANAGEMENTBASEPATH`    | Base path for management endpoints                                          | `${management.server.base-path}`        |
| `FLOWX_PLATFORMHEALTH_ACTUATORBASEPATH`      | Base path for actuator endpoints                                            | `${management.endpoints.web.base-path}` |
| `FLOWX_PLATFORMHEALTH_ANNOTATIONNAME`        | Kubernetes annotation name for health checks                                | `flowx.ai/health`                       |
| `FLOWX_PLATFORMHEALTH_ANNOTATIONVALUE`       | Kubernetes annotation value for health checks                               | `true`                                  |
| `FLOWX_PLATFORMHEALTH_DISCOVERYINTERVAL`     | Interval at which the platform re-discovers deployed services automatically | `PT5M`                                  |
| `FLOWX_PLATFORMHEALTH_DISCOVERYINITIALDELAY` | Delay before the first automatic service discovery run after startup        | `PT30S`                                 |

***

## Multi-edit and undo/redo configuration

| Environment Variable                    | Description                                     | Default Value |
| --------------------------------------- | ----------------------------------------------- | ------------- |
| `FLOWX_MULTIEDIT_TTL`                   | Time-to-live for multi-edit sessions in seconds | `45`          |
| `FLOWX_UNDOREDO_TTL`                    | Time-to-live for undo/redo actions in seconds   | `86400`       |
| `FLOWX_UNDOREDO_CLEANUP_CRONEXPRESSION` | Cron expression for undo/redo cleanup           | `0 0 2 ?`     |
| `FLOWX_UNDOREDO_CLEANUP_DAYS`           | Days to keep deleted undo/redo items            | `2`           |

***

## Resources usage configuration

| Environment Variable                                                      | Description                                           | Default Value                             |
| ------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------- |
| `FLOWX_LIB_RESOURCESUSAGES_ENABLED`                                       | Enable resources usage tracking                       | `true`                                    |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_ENABLED`                       | Enable listener for resource usage refreshes          | `true`                                    |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_THREADCOUNT`         | Thread count for resource usage collector             | `5`                                       |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_MAXBATCHSIZE`        | Maximum batch size for resource usage collection      | `1000`                                    |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_GROUPID_RESOURCESUSAGESREFRESH` | Consumer group ID for resource usage refresh          | `admin-resources-usages-refresh-group`    |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_THREADS_RESOURCESUSAGESREFRESH` | Number of consumer threads for resource usage refresh | `3`                                       |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_TOPIC_RESOURCE_USAGES_REFRESH`           | Kafka topic for resource usage refresh                | `${kafka.topic.resources-usages.refresh}` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_AUTHEXCEPTIONRETRYINTERVAL`              | Retry interval in seconds after auth exceptions       | `3`                                       |

***

## Authentication and Authorization Configuration

The FlowX Admin microservice supports authentication and authorization through OpenID Connect (with Keycloak as the default provider) and allows detailed role-based access control.

### Security type

| Environment Variable                                      | Description                                                           | Default Value                          |
| --------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------- |
| `SECURITY_TYPE`                                           | Token validation mechanism (JWT public key validation)                | `jwt-public-key`                       |
| `SECURITY_OAUTH2CLIENT`                                   | Enable OAuth2 client                                                  | `enabled`                              |
| `SECURITY_OAUTH2_BASESERVERURL`                           | Base URL of the Keycloak server                                       |                                        |
| `SECURITY_OAUTH2_SAREALM`                                 | Service-accounts realm ID                                             | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80`       |

### Service account configuration

The Admin service authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable                                                        | Description                                                                                                                                           | Default Value                                                                                      |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`          | Service account client ID                                                                                                                             | `flowx-admin-sa`                                                                                   |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`      | Service account client secret (Keycloak-issued)                                                                                                       |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID`     | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa`                                                                               |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret                                                                                                               |                                                                                                    |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI`          | Provider token URI, resolved against the service-accounts realm                                                                                       | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

<Warning>
  **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. The `OPENID_PROVIDER` / `OPENID_KEYCLOAK_*` / `OPENID_ENTRA_*` identity-provider block was also removed from the Admin service in 5.9.0. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

<Info>
  When deploying with the FlowX Helm chart, `SECURITY_OAUTH2_BASESERVERURL` is supplied through the chart value `flowx.keycloak.baseServerUrl` and the service-account client secrets are injected from the chart-managed Keycloak secret. The remaining values ship as image defaults.
</Info>

### Designer authentication client

| Environment Variable          | Description                          | Default Value                 |
| ----------------------------- | ------------------------------------ | ----------------------------- |
| `FLOWX_AUTHENTICATE_CLIENTID` | Client ID for authentication service | `flowx-platform-authenticate` |

<Info>
  The role-based access control is configured in the application YAML and grants specific permissions for platform management, user management, process management, integrations management, and configuration management.
</Info>

***

## Ingress and CORS

The Admin service is exposed externally on the admin host. 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 route

| Host group | External path | Backend receives |
| ---------- | ------------- | ---------------- |
| admin      | `/`           | `/`              |

The path is set through `services.admin.ingress.admin.path` (or `services.admin.gateway.admin.paths`) in the chart values. Override only if you serve FlowX Admin under a different prefix.

### 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 and integration domain that issues browser requests against Admin. | `-`           |

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

<Warning>
  In production environments, never use the default service account credentials. Always configure secure, environment-specific credentials for authentication.
</Warning>

<Warning>
  Sensitive information such as passwords and client secrets should be managed securely using environment variables or a secrets management solution in production environments.
</Warning>

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Admin service fails to start">
    **Symptoms:** Service crashes on startup or fails health checks.

    **Solutions:**

    1. Verify PostgreSQL connection parameters (`SPRING_DATASOURCE_URL`, credentials) are correct and the database is reachable
    2. Check that MongoDB is running and the connection URI is valid
    3. Ensure Kafka brokers are accessible at the configured `SPRING_KAFKA_BOOTSTRAPSERVERS` address
    4. Review startup logs for specific error messages indicating which dependency is unavailable
  </Accordion>

  <Accordion title="Cannot export or import resources">
    **Symptoms:** Import/export operations fail with permission or authentication errors.

    **Solutions:**

    1. Verify the Keycloak service account has the required roles for import/export operations
    2. Check that `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` and `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` are configured correctly
    3. Ensure the service account has `canImport` access rights in the target workspace
    4. Confirm the target application version is in a WIP state
  </Accordion>

  <Accordion title="Build creation fails">
    **Symptoms:** Creating a build returns errors or times out.

    **Solutions:**

    1. Check connectivity between Admin and the application-manager service
    2. Verify that the Kafka topics for build operations (`KAFKA_TOPIC_BUILD_RUNTIMEDATA`) are created and accessible
    3. Ensure version compatibility between Admin and application-manager services
    4. Review Kafka consumer group lag for build-related topics
  </Accordion>

  <Accordion title="UI not loading in Designer">
    **Symptoms:** Designer interface fails to render or returns blank pages.

    **Solutions:**

    1. Verify the Designer service is running and healthy
    2. Check ingress configuration — ensure the Admin ingress (`admin-admin`) is correctly routing traffic
    3. Review CORS settings in the [Ingress Configuration Guide](./ingress-configuration)
    4. Confirm that the `Fx-Workspace-Id` header is being passed correctly through the ingress
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Configuring an IAM Solution" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup for Keycloak and Microsoft Entra ID
  </Card>

  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Complete Redis setup including Sentinel and Cluster modes
  </Card>

  <Card title="Ingress Configuration" icon="network-wired" href="./ingress-configuration">
    Centralized ingress guide with CORS configuration and best practices
  </Card>
</CardGroup>