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

# Update environment variables

> Environment variable changes when upgrading from FlowX.AI v5.4.0 to v5.5.0

<Info>
  This page details environment variable changes required for the v5.4.0 to v5.5.0 upgrade. For the full migration context, see the [Migration Overview](./migration-overview).
</Info>

## Authentication variables (all affected services)

The following changes apply to **14 of 19 platform services** as part of the authentication mechanism change from `oauth2` to `jwt-public-key`.

### Variables to remove

Remove these variables from your Helm values, environment configs, or deployment manifests:

```yaml theme={"system"}
# Opaque-token introspection (removed entirely)
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI:  # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID:          # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET:      # REMOVE

# Legacy OAuth2 client variables
SECURITY_OAUTH2_REALM:                                                   # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_ID:                                        # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET:                                    # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID:                         # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET:                     # REMOVE
```

### Variables to update

<Tabs>
  <Tab title="Before (v5.4)">
    ```yaml theme={"system"}
    SECURITY_TYPE: "oauth2"

    # Service account client ID (example for admin service)
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "${security.oauth2.service-account.admin.client-id}"
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "${security.oauth2.service-account.admin.client-secret}"

    # Token URI using main realm
    SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token"
    ```
  </Tab>

  <Tab title="After (v5.5)">
    ```yaml theme={"system"}
    SECURITY_TYPE: "jwt-public-key"

    # Service account client ID follows flowx-{service-name}-sa pattern
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "flowx-admin-sa"
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "{your-client-secret}"

    # Token URI now uses separate sa-realm
    SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.sa-realm}/protocol/openid-connect/token"
    ```
  </Tab>
</Tabs>

***

## New platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable       | Description                                      | Default Value      | Component                                                                                                                             |
| -------------------------- | ------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `KAFKA_MESSAGE_MAX_BYTES`  | Maximum Kafka producer message size in bytes     | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL`                | Redis cache time-to-live in milliseconds         | `5000000`          | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin                               |
| `KAFKA_OAUTH_CLIENT_ID`    | OAuth client ID for Kafka SASL authentication    | `kafka`            | events-gateway, email-gateway, notification-plugin, document-plugin                                                                   |
| `LOGGING_LEVEL_APP`        | Application-specific logging level               | `INFO`             | Most services (12/19)                                                                                                                 |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF`              | Most services (12/19)                                                                                                                 |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level                     | `INFO`             | admin, application-manager, cms-core                                                                                                  |

***

## Document plugin

| Environment Variable        | Description                                        | Default Value      |
| --------------------------- | -------------------------------------------------- | ------------------ |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) |

***

## Email gateway

<Info>
  **New in 5.5.0** — The email gateway service supports IMAP polling for email triggers. The following variables control polling behavior and load balancing.
</Info>

| Environment Variable                       | Description                                                    | Default Value    |
| ------------------------------------------ | -------------------------------------------------------------- | ---------------- |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT`    | IMAP server connection timeout in milliseconds                 | `10000`          |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS`  | Maximum number of concurrent IMAP polling operations           | `30`             |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle                    | `50`             |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL`      | Interval between IMAP polling cycles in seconds                | `30`             |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT`          | IMAP read timeout in milliseconds                              | `30000`          |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON`       | Cron expression for master election checks                     | `*/5 * * * * *`  |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL`        | Master election TTL in seconds                                 | `15`             |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE`    | Maximum email accounts per service instance for load balancing | `100`            |
| `EMAIL_GATEWAY_REBALANCING_CRON`           | Cron expression for email account rebalancing                  | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS`      | Timeout in seconds before marking an instance as stale         | `90`             |

***

## Additional resources

<CardGroup cols={2}>
  <Card title="Migration Overview" href="./migration-overview" icon="book">
    Full migration guide with Keycloak and service account changes
  </Card>

  <Card title="Deployment Guidelines v5.5.0" href="../deployment-guidelines-v5.5" icon="rocket">
    Component versions, Kafka topics, and infrastructure requirements
  </Card>
</CardGroup>