> ## 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.
# API & integration breaking changes
> REST endpoint renames, removals, mandatory headers, and token-format changes that custom API clients and integrations must adapt to between 5.1.x and 5.9.x.
5.1.x deployments expose a stable surface of REST endpoints that internal Designer and renderer code, custom integrations, and direct API consumers depend on. The 5.1 → 5.9 jump introduces four REST-surface changes that custom callers must adapt to: one endpoint rename, one feature removal, one new mandatory request header, and one authentication-token-format change. None of these affect Designer or the FlowX-shipped renderer SDKs. Those are managed automatically when you upgrade. The audit work is for whatever calls FlowX from outside.
A fifth change is internal to the platform but affects the runtime behavior of existing JavaScript and Python scripts: the default script execution engine moves from GraalVM polyglot contexts to a native Node.js + CPython subprocess pool. Most scripts keep working unchanged; a small subset that relied on GraalVM-specific behavior must be adapted, or kept on GraalVM via an opt-out env var.
If your deployment only uses FlowX through Designer and the shipped renderer SDKs, you can skim this page. If you have **custom API clients, custom integrations, or scripts that call the FlowX REST API directly**, or if you wrote **JavaScript or Python business rules / workflow scripts** in your project, work through every section.
***
## Process start metadata endpoint renamed
The endpoint that returns the JSON shape required to start a process was renamed and its response extended.
| Before (5.1.x) | After (5.9.x) |
| --------------------------------------------------- | ------------------------------------------------------- |
| `GET /api/process-definition/{uuid}/get-input-json` | `GET /api/process-definition/{uuid}/get-start-metadata` |
The response gains a `hasEmailTriggerStart` boolean field that tells the caller whether the process can be started by an inbound email trigger. Existing response fields are unchanged.
Update any direct API clients, Postman collections, scripts, or upstream integration code that hard-codes the old path. The old path returns a 404 after upgrade.
***
## Configure Environment Info feature deprecated
The Configure Environment Info feature, which let operators set a human-readable environment name (Dev / Staging / Production) from the Designer Platform Status page, is deprecated. Environment name now comes from organization registration and workspace types instead.
### `PATCH /api/platform/environment` endpoint removed
The endpoint that updated the environment name is removed. Any caller that issues a `PATCH` against this path receives a 404.
### `environmentDetails` field in `/api/init` is deprecated
The `environmentDetails` block in the `/api/init` response is deprecated. Designer no longer reads it, and new clients should switch to the dedicated `/env` endpoint. The field is still present in the response during the deprecation window for backward compatibility, but direct API consumers should treat it as a stale source and migrate.
### Environment-name env vars no longer used
The following environment variables are no longer consumed by any service and should be removed from your deployment manifests during the upgrade:
| Removed env var | Replacement |
| ------------------------ | ---------------------------------------------------------------- |
| `FLOWX_CLIENT_NAME` | Organization name set during registration |
| `FLOWX_ENVIRONMENT_NAME` | Workspace type (Sandbox / Staging / Production) on the workspace |
See [Organization & deployment configuration](./organization-deployment) for organization registration and workspace types.
***
## `Fx-Organization-Id` header mandatory for REST clients
Self-hosted deployments now run in single-organization mode by default. Every REST request that targets an organization-scoped endpoint must include the organization UUID as a request header:
```http theme={"system"}
Fx-Organization-Id:
```
The header is required on every organization-scoped REST endpoint: process runtime, task management, document plugin, audit query, and any other endpoint that returns data scoped to your organization. Without the header, requests fail with a client error before reaching the business logic. Designer and the FlowX renderer SDKs set the header automatically from the current session. The audit applies to custom callers only.
If you have custom integrations that span multiple endpoint surfaces, your FlowX representative can confirm which specific endpoints in your integration pattern require the header before you start the upgrade.
Your FlowX representative provides the organization UUID during the upgrade. See [Organization & deployment configuration](./organization-deployment) for where to obtain it and [Kafka migration](./kafka) for the matching Kafka-side header rule.
***
## Script runtime change for JavaScript and Python business rules
The default execution engine for JavaScript and Python business rules and workflow scripts moves from GraalVM polyglot contexts to a native subprocess pool (Node.js for JavaScript, CPython 3.11 for Python). The change is transparent for the vast majority of scripts, but a small subset that relied on GraalVM-specific behavior must be adapted, or kept on GraalVM via an opt-out environment variable.
| Aspect | Before (5.1.x) | After (5.9.x) |
| ----------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| JavaScript runtime | GraalJS on GraalVM 24.x | Node.js V8 |
| Python runtime | GraalPy on GraalVM 24.x | CPython 3.11 |
| `input` / `output` / `additionalData` / `instanceMetadata` bindings | Available | Available, unchanged |
| `output.put(...)` / `output.get(...)` / `output.containsKey(...)` | Java HashMap methods | Preserved on both JavaScript and Python |
| Python `import` of arbitrary stdlib | Allowed | Curated allowlist: `random`, `math`, `datetime`, `re`, `hashlib`, `decimal`, `copy`, `string`, `collections`, `itertools`, `functools`, `uuid`, `base64` are pre-loaded and ready to use; other modules are blocked |
| JavaScript `require(...)` / `process` / `global` | Worked via GraalVM polyglot context | Not available; scripts run in an isolated V8 context with an explicit globals allowlist |
| Calling Java classes from scripts (`Java.type(...)`, polyglot bindings) | Worked via GraalVM | Not available on the native engine |
### What you do not need to change
Scripts that only read from `input`, write to `output`, and use language built-ins (object/dict access, arithmetic, string methods, JSON, the pre-loaded Python modules above) keep working without modification.
### What to audit before upgrading
1. **Python `import` statements.** Search Python business-rule and workflow scripts for `import` lines that pull in modules outside the curated allowlist above. Narrow the script to use only allowed modules, or plan to stay on GraalVM via the opt-out env var below.
2. **JavaScript `require(...)`, `process`, `global` references.** Search JavaScript scripts for these tokens. They were not officially part of the supported surface area but may have worked under GraalVM. Rewrite to use only the provided bindings, or stay on GraalVM.
3. **Polyglot calls into Java classes.** Search for `Java.type`, `java.util.`, `org.springframework.` in scripts. These only worked under GraalVM and have no equivalent on the native engine. Stay on GraalVM if you depend on them.
### How to keep the GraalVM engine
Set the following on both `process-engine` and `integration-designer`:
```yaml theme={"system"}
APPLICATION_SCRIPT_ENGINE_PROVIDER: graalvm
```
GraalVM is bundled and supported alongside the native engine. Use this as a transitional setting while you adapt scripts, or as a permanent setting if you have a strong reason to keep polyglot behavior.
See [Native script engine for JavaScript and Python](/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026#native-script-engine-for-javascript-and-python) in the 5.9.0 release notes for the full feature card.
***
## Direct API clients using opaque tokens must switch to JWT
FlowX services moved to validating signed JWT bearer tokens against Keycloak's public key. Opaque reference tokens, session cookies, and other non-JWT bearer strings are no longer accepted as the default and may not be supported at all on the affected services. Confirm with your FlowX representative if your integrations rely on them.
This change is transparent for callers that already use JWT bearer tokens issued by Keycloak (Designer, renderer SDKs, anything using the standard OIDC flow). It only affects **direct API clients** that obtain non-JWT credentials.
Such clients must obtain a signed JWT access token from Keycloak (standard `client_credentials` or `password` grants returning a JWT) and pass it as `Authorization: Bearer `.
See [Authentication & IAM migration](./authentication-iam) for the full Keycloak two-realm architecture and the service-account client renames that go alongside this change.
***
## Pre-upgrade audit
For each of your custom API clients and integrations, confirm:
Search your codebase, Postman collections, API gateway rules, and shell scripts for the strings `get-input-json` and `/api/platform/environment`. Update the first to `get-start-metadata`; remove any `PATCH` calls to the second.
Search for callers that parse the `environmentDetails` block out of `/api/init`. Plan their migration to the `/env` endpoint.
Confirm every REST call from custom code includes `Fx-Organization-Id`. Add it via your HTTP client's default-header configuration if not already centralized.
Confirm every custom API client uses a JWT bearer token from Keycloak. Not an opaque reference token, session cookie, or API key. Update token-acquisition code if necessary.
Remove `FLOWX_CLIENT_NAME` and `FLOWX_ENVIRONMENT_NAME` from Helm values, deployment manifests, and any out-of-band env files. They are silently ignored on 5.9.x.
Search business-rule and workflow scripts for: Python `import` statements pulling modules outside the curated allowlist; JavaScript `require(...)`, `process`, or `global` references; calls into Java classes (`Java.type`, `java.util.`, `org.springframework.`). Adapt the scripts or set `APPLICATION_SCRIPT_ENGINE_PROVIDER=graalvm` on `process-engine` and `integration-designer` to keep the GraalVM engine.
***
## Related resources
Keycloak two-realm architecture, service-account client renames, opaque-token removal.
Organization UUID, single-org default mode, removed env-info env vars.
`Fx-Organization-Id` on Kafka producers; new topics and ownership moves.
Return to the migration hub.