AI Gateway setup

The AI Gateway is a core service that owns the Designer AI chat surface. It streams AI assistant responses to the browser over Server-Sent Events (SSE) and routes chat requests to the config-time agents.

Dependencies

Before setting up the AI Gateway, ensure you have the following dependencies in place:

MongoDB for storing conversation context
Keycloak (or compatible OAuth2 provider) for authentication and authorization
SpiceDB for fine-grained, workspace-level authorization on AI interactions
AI Platform — the config-time agents the gateway routes chat requests to

Infrastructure prerequisites

Component	Description
MongoDB	Stores AI chat conversation context
Keycloak	Identity provider for service authentication
SpiceDB	Authorization service for workspace validation
AI Platform	Config-time agents that handle chat requests

Configuration

Authorization configuration

The AI Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the mainIdentity client registration) in the service-accounts realm:

Environment Variable	Description	Default Value
`SECURITY_TYPE`	Token validation mechanism (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`
`FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL`	URL of the organization-manager service, used by the security library	`http://organization-manager:80`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID`	Service account client ID	`flowx-ai-gateway-sa`
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`	Service account client secret (Keycloak-issued)
`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`

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. See the authentication and IAM migration guide for the full list.

AI Platform routing

The AI Gateway forwards chat requests to the config-time agents and the planner. In Kubernetes these default to the in-cluster service names — override them only for custom networking or mixed deployments.

Starting with 5.9.2, AI Platform services are deployed under their plain names — the ai-platform- prefix is dropped. The defaults below reflect the new names. If you upgrade the core services and the AI Platform chart separately, or you overrode these variables with the old prefixed names, align them — mixed naming breaks AI features. See the 5.9.2 deployment guidelines.

Environment Variable	Description	Default Value
`FLOWX_PLANNER_HOST`	Planner service hostname	`planner`
`FLOWX_PLANNER_PORT`	Planner service port	`9100`
`FLOWX_AGENTS_AIANALYST_BASEURL`	AI Analyst agent base URL	`http://ai-analyst:9100`
`FLOWX_AGENTS_AIARCHITECT_BASEURL`	AI Architect agent base URL	`http://ai-architect:9100`
`FLOWX_AGENTS_AIASSISTANT_BASEURL`	AI Assistant agent base URL	`http://ai-assistant:9100`
`FLOWX_AGENTS_AIDESIGNER_BASEURL`	AI Designer agent base URL	`http://ai-designer:9100`
`FLOWX_AGENTS_AIDEVELOPER_BASEURL`	AI Developer agent base URL	`http://ai-developer:9100`
`FLOWX_DOCUMENTPLUGIN_BASEURL`	Document plugin base URL	`http://document-plugin:80`

MongoDB configuration

Environment Variable	Description	Default Value
`SPRING_DATA_MONGODB_URI`	MongoDB connection URI	-

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. Keep the default unless instructed by FlowX.	`CUSTOM`

Logging configuration

Environment Variable	Description	Default Value
`LOGGING_LEVEL_ROOT`	Root logging level	`INFO`
`LOGGING_LEVEL_APP`	Application-specific log level	`INFO`

Secrets management

Secret Name	Description
`SPRING_DATA_MONGODB_URI`	MongoDB connection URI (contains credentials)
`SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`	Keycloak service account secret
`FLOWX_SPICEDB_TOKEN`	SpiceDB authentication token

Ingress and CORS

The AI Gateway is exposed on the admin host because the Designer connects to it directly from the browser. Because it streams chat responses over SSE, the ingress must allow long-lived connections — the FlowX deploy chart raises the default proxy read/send timeouts for this service so streams are not cut mid-flight.

CORS configuration

Environment Variable	Description	Default Value
`APPLICATION_CORS_ALLOWORIGIN`	Comma-separated list of origins allowed to call this service from the browser. Must include every Designer domain that uses AI chat. Supports wildcard subdomains (`https://*.yourcompany.com`).	`-`

Allowed methods, allowed headers, and credential handling are baked into the service’s application.yaml with safe defaults. For the complete route reference and Gateway API HTTPRoute configuration, see the ingress configuration guide.

Deployment

Helm values example

fullnameOverride: ai-gateway

image:
  repository: <your-registry>/ai-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # OAuth2
  SECURITY_TYPE: oauth2
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

  # CORS — origins that use the Designer AI chat
  APPLICATION_CORS_ALLOWORIGIN: https://designer.example.com

extraEnvVarsMultipleSecretsCustomKeys:
  - name: mongodb-generic
    secrets:
      SPRING_DATA_MONGODB_URI: mongodb-uri
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: true
  admin:
    enabled: true

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/routing-name: "ai-gateway"
  flowx.ai/prometheus-scrape: "ai-gateway"

The AI Gateway requires ingress to be enabled because the Designer connects to it from the browser to open AI chat streams.

Verify your setup

The AI Gateway pod is running and healthy: kubectl get pods -l app=ai-gateway

The health endpoint returns HTTP 200: curl http://ai-gateway:8080/actuator/health

SpiceDB connection is established — check pod logs for successful CAS client initialization

AI chat opens in the Designer and streams a response without the connection dropping

Troubleshooting

AI chat stream drops mid-response

Solutions:

Confirm the ingress proxy read/send timeouts are raised for the AI Gateway route (SSE needs long-lived connections)
Check that no intermediate proxy buffers or closes the SSE stream
Review pod logs for upstream errors from the config-time agents

AI chat returns a CORS error in the browser

Solutions:

Add the Designer origin to APPLICATION_CORS_ALLOWORIGIN
Verify the request reaches the AI Gateway on the admin host

SpiceDB connection failures

Solutions:

Verify SpiceDB is running and reachable at the configured host and port
Check that the SpiceDB token is correct
Ensure network policies allow gRPC traffic to SpiceDB on port 50051

AI Platform setup

Config-time agents and AI infrastructure

SpiceDB Configuration

Fine-grained authorization setup

IAM Configuration

Identity and access management setup

Ingress configuration

Routing and CORS reference

Microservices

AI Platform

Plugins

Observability

Access management

AI Gateway setup

Dependencies

Infrastructure prerequisites

Configuration

Authorization configuration

AI Platform routing

MongoDB configuration

CAS lib configuration (SpiceDB)

Logging configuration

Secrets management

Ingress and CORS

CORS configuration

Deployment

Helm values example

Verify your setup

Troubleshooting

AI Platform setup

SpiceDB Configuration

IAM Configuration

Ingress configuration

​Dependencies

​Infrastructure prerequisites

​Configuration

​Authorization configuration

​AI Platform routing

​MongoDB configuration

​CAS lib configuration (SpiceDB)

​Logging configuration

​Secrets management

​Ingress and CORS

​CORS configuration

​Deployment

​Helm values example

​Verify your setup

​Troubleshooting

​Related resources

AI Platform setup

SpiceDB Configuration

IAM Configuration

Ingress configuration

Dependencies

Infrastructure prerequisites

Configuration

Authorization configuration

AI Platform routing

MongoDB configuration

CAS lib configuration (SpiceDB)

Logging configuration

Secrets management

Ingress and CORS

CORS configuration

Deployment

Helm values example

Verify your setup

Troubleshooting

Related resources