Skip to main content

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.

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

Environment VariableDescriptionDefault Value
SECURITY_TYPESecurity typeoauth2
SECURITY_OAUTH2_BASE_SERVER_URLBase URL of the OAuth2/OIDC server
SECURITY_OAUTH2_REALMOAuth2 realm name
SECURITY_OAUTH2_CLIENT_CLIENT_IDClient ID for token introspection
SECURITY_OAUTH2_CLIENT_CLIENT_SECRETClient secret for token introspection
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_IDService account client IDflowx-ai-gateway-sa
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETService account client secret

​
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)
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETKeycloak 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_BASE_SERVER_URL: 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 2, 2026