Skip to main content
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

ComponentDescription
MongoDBStores AI chat conversation context
KeycloakIdentity provider for service authentication
SpiceDBAuthorization service for workspace validation
AI PlatformConfig-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 VariableDescriptionDefault Value
SECURITY_TYPEToken validation mechanism (JWT public key validation)jwt-public-key
SECURITY_OAUTH2_BASESERVERURLBase URL of the Keycloak server
SECURITY_OAUTH2_SAREALMService-accounts realm ID00000002-0002-4002-8002-000000000002
FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURLURL of the organization-manager service, used by the security libraryhttp://organization-manager:80
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTIDService account client IDflowx-ai-gateway-sa
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRETService account client secret (Keycloak-issued)
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURIProvider 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.

​
MongoDB configuration

Environment VariableDescriptionDefault Value
SPRING_DATA_MONGODB_URIMongoDB connection URI-

​
CAS lib configuration (SpiceDB)

Environment VariableDescriptionDefault Value
FLOWX_SPICEDB_HOSTSpiceDB hostnamespicedb
FLOWX_SPICEDB_PORTSpiceDB gRPC port50051
FLOWX_SPICEDB_TOKENSpiceDB authentication token-
FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATIONRuntime authorization backend used by the CAS client. Keep the default unless instructed by FlowX.CUSTOM

​
Logging configuration

Environment VariableDescriptionDefault Value
LOGGING_LEVEL_ROOTRoot logging levelINFO
LOGGING_LEVEL_APPApplication-specific log levelINFO

​
Secrets management

Secret NameDescription
SPRING_DATA_MONGODB_URIMongoDB connection URI (contains credentials)
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRETKeycloak service account secret
FLOWX_SPICEDB_TOKENSpiceDB 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 VariableDescriptionDefault Value
APPLICATION_CORS_ALLOW_ORIGINComma-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_ALLOW_ORIGIN: 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

Solutions:
  1. Confirm the ingress proxy read/send timeouts are raised for the AI Gateway route (SSE needs long-lived connections)
  2. Check that no intermediate proxy buffers or closes the SSE stream
  3. Review pod logs for upstream errors from the config-time agents
Solutions:
  1. Add the Designer origin to APPLICATION_CORS_ALLOW_ORIGIN
  2. Verify the request reaches the AI Gateway on the admin host
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

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
Last modified on June 4, 2026