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

# AI Gateway setup

> Set up the AI Gateway microservice — powers the AI chat experience in the FlowX Designer, streaming AI assistant responses to the browser and routing requests to the config-time agents.

<Info>
  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.
</Info>

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

<Warning>
  **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](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
</Warning>

***

### 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_ALLOW_ORIGIN` | 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](./ingress-configuration).

***

## Deployment

### Helm values example

```yaml theme={"system"}
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"
```

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

***

## Verify your setup

<Check>
  The AI Gateway pod is running and healthy: `kubectl get pods -l app=ai-gateway`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://ai-gateway:8080/actuator/health`
</Check>

<Check>
  SpiceDB connection is established — check pod logs for successful CAS client initialization
</Check>

<Check>
  AI chat opens in the Designer and streams a response without the connection dropping
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="AI chat stream drops mid-response">
    **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
  </Accordion>

  <Accordion title="AI chat returns a CORS error in the browser">
    **Solutions:**

    1. Add the Designer origin to `APPLICATION_CORS_ALLOW_ORIGIN`
    2. Verify the request reaches the AI Gateway on the admin host
  </Accordion>

  <Accordion title="SpiceDB connection failures">
    **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`
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="AI Platform setup" icon="hand-sparkles" href="../ai-platform/ai-platform-setup">
    Config-time agents and AI infrastructure
  </Card>

  <Card title="SpiceDB Configuration" icon="shield-halved" href="./spicedb">
    Fine-grained authorization setup
  </Card>

  <Card title="IAM Configuration" icon="key" href="./access-management/configuring-an-iam-solution">
    Identity and access management setup
  </Card>

  <Card title="Ingress configuration" icon="route" href="./ingress-configuration">
    Routing and CORS reference
  </Card>
</CardGroup>