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.

​
Dependencies

Before setting up the License service, ensure you have the following dependencies in place:
  • Organization Manager for organization lifecycle events and realm resolution
  • PostgreSQL database for storing license and usage data
  • Kafka for event-driven communication with other FlowX.AI services
  • Redis for caching and master election
  • Keycloak (or compatible OAuth2 provider) for authentication and authorization
  • SpiceDB for fine-grained authorization

​
Infrastructure prerequisites

ComponentDescription
PostgreSQLDedicated database for license data
KafkaMessage broker for inter-service communication
RedisCaching layer and distributed lock for master election
KeycloakIdentity provider for service authentication
SpiceDBAuthorization service for fine-grained access control

​
Configuration

​
Authorization configuration

Environment VariableDescriptionDefault Value
SECURITY_TYPESecurity type (JWT public key validation)jwt-public-key
SECURITY_OAUTH2_BASE_SERVER_URLBase URL of the Keycloak server
SECURITY_OAUTH2_SAREALMService accounts realm ID00000002-0002-4002-8002-000000000002
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_IDService account client IDflowx-license-sa
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETService account client secret
FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURLOrganization manager URLhttp://organization-manager:80

​
PostgreSQL configuration

The License service uses its own dedicated PostgreSQL database.
Environment VariableDescriptionDefault Value
SPRING_DATASOURCE_URLJDBC connection URL for PostgreSQLjdbc:postgresql://flowxlicensedb:5432/license
SPRING_DATASOURCE_USERNAMEDatabase usernamepostgres
SPRING_DATASOURCE_PASSWORDDatabase password-
PostgreSQL and Redis credentials: plain env vars still work. The License service is a standard Spring Boot service — it reads the SPRING_DATASOURCE_* and SPRING_DATA_REDIS_* environment variables shown here. The postgresql.servers/credentials and redis.servers/credentials blocks in the FlowX Helm chart’s values.yaml are the chart’s own secret-to-env-var mapping; they exist to template the same plain env vars from your secrets. You can keep injecting credentials through plain environment variables exactly as before.
Ensure the database is created before deploying the service. The License service will manage its own schema migrations via Liquibase.

​
Redis configuration

The License service includes Redis in its configuration for caching and master election. Configure Redis connection using the standard Redis environment variables. Quick reference:
Environment VariableDescriptionExample ValueStatus
SPRING_DATA_REDIS_HOSTRedis server hostnamelocalhostRecommended
SPRING_DATA_REDIS_PORTRedis server port6379Recommended
SPRING_DATA_REDIS_PASSWORDRedis authentication password-Recommended
REDIS_TTLCache TTL in milliseconds5000000Optional
Both SPRING_DATA_REDIS_* and SPRING_REDIS_* variable prefixes are supported. The SPRING_DATA_REDIS_* prefix is the modern Spring Boot standard and is recommended for new deployments.
For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the Redis Configuration guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.
Redis is configured but not actively used by the License service at this time. It is included as part of the standard Spring service setup and may be used in future versions.

​
Kafka configuration

​
Core Kafka settings

Environment VariableDescriptionDefault Value
SPRING_KAFKA_BOOTSTRAP_SERVERSAddress of the Kafka server(s)localhost:9092
KAFKA_MESSAGE_MAX_BYTESMaximum message size (bytes)52428800 (50 MB)

​
Topic naming configuration

Environment VariableDescriptionDefault Value
KAFKA_TOPIC_NAMING_PACKAGEPackage prefix for topic namesai.flowx.
KAFKA_TOPIC_NAMING_ENVIRONMENTEnvironment segment for topic names
KAFKA_TOPIC_NAMING_VERSIONVersion suffix for topic names.v1
KAFKA_TOPIC_NAMING_SEPARATORPrimary separator for topic names.
KAFKA_TOPIC_NAMING_SEPARATOR2Secondary separator for topic names-

​
Kafka topics

The License service consumes events from the following topics:
TopicDefault ValueDescription
License usageai.flowx.license.usage.v1Receives usage reporting events from other services
Organization eventsai.flowx.organization.events.v1Receives organization lifecycle events

​
Kafka consumer threads

Environment VariableDescriptionDefault Value
KAFKA_CONSUMER_THREADS_LICENSE_USAGEThread count for license usage consumer6
KAFKA_CONSUMER_THREADS_ORGANIZATION_EVENTSThread count for organization events consumer2
KAFKA_AUTH_EXCEPTION_RETRY_INTERVALRetry interval after auth exception (seconds)10

​
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. CUSTOM routes checks through authorization-system; SPICEDB delegates to SpiceDB. Keep the default unless instructed by FlowX.CUSTOM

​
FlowX SaaS connection (self-hosted only)

Environment VariableDescriptionDefault Value
FLOWX_LICENSE_ORGANIZATION_IDOrganization ID provided by FlowX during self-hosted registration. Initialized with the notset sentinel so the OAuth client can start before the self-hosted client injects the real value at runtime.notset
FLOWX_LICENSE_KEYLicense key issued by FlowX for this self-hosted deployment.-
FLOWX_LICENSE_AUTH_SERVER_URLAuth endpoint provided by FlowX licensing.-
FLOWX_LICENSE_SERVER_URLLicense API endpoint provided by FlowX licensing.-
These values are provided by FlowX during the organization registration process. Without them, the License service cannot validate the platform license or report usage data.Your network must allow outbound connectivity to the FlowX SaaS endpoints configured above.

​
Usage upload tuning

The License service periodically uploads usage records to FlowX SaaS. These defaults work for most deployments and only need tuning for very large organizations:
Environment VariableDescriptionDefault Value
FLOWX_SCHEDULER_USAGEUPLOAD_LOADFETCHSIZENumber of usage records loaded from the database per scheduler tick100
FLOWX_SCHEDULER_USAGEUPLOAD_UPLOADBATCHSIZENumber of usage records sent per upload request to FlowX SaaS500

​
Logging configuration

Environment VariableDescriptionDefault Value
LOGGING_LEVEL_APPApplication-specific log levelINFO
LOGGING_LEVEL_LIQUIBASELiquibase migration log levelINFO

​
Secrets management

The License service requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.
Secret NameDescription
SPRING_DATASOURCE_PASSWORDPostgreSQL database password
SPRING_REDIS_PASSWORDRedis authentication password
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRETKeycloak service account secret
FLOWX_SPICEDB_TOKENSpiceDB authentication token

​
Deployment

​
Helm values example

Below is an example Helm values configuration for deploying the License service: 
fullnameOverride: license

image:
  repository: <your-registry>/license

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/license
  SPRING_DATASOURCE_USERNAME: postgres

  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092

  # Security
  SECURITY_TYPE: jwt-public-key
  SECURITY_OAUTH2_BASE_SERVER_URL: https://keycloak.example.com/auth
  SECURITY_OAUTH2_SAREALM: 00000002-0002-4002-8002-000000000002

  # Redis
  SPRING_REDIS_HOST: redis-master

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: redis-generic
    secrets:
      SPRING_REDIS_PASSWORD: redis-password
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: keycloakLicenseClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: false

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/egress-s-redis: "true"
  flowx.ai/routing-name: "license"
  flowx.ai/prometheus-scrape: "license"

​
Network policies

The License service requires network access to the following services:
ServicePurposePod Label
KafkaMessage broker communicationflowx.ai/egress-s-kafka
PostgreSQLPrimary data storageflowx.ai/egress-s-postgresql
RedisCaching and master electionflowx.ai/egress-s-redis
KeycloakAuthenticationflowx.ai/egress-s-keycloak
SpiceDBAuthorizationflowx.ai/egress-s-spicedb

​
Monitoring

The License service exposes Prometheus metrics for monitoring. Turn on scraping by setting the pod label: 
podLabels:
  flowx.ai/prometheus-scrape: "license"

​
Health endpoints

EndpointDescription
/actuator/healthHealth check endpoint
/actuator/metricsPrometheus metrics endpoint
/actuator/infoApp info endpoint

​
Verify your setup

The License service pod is running and healthy: kubectl get pods -l app=license
The health endpoint returns HTTP 200: curl http://license:8080/actuator/health
Database migrations completed successfully — check pod logs for Liquibase: Update has been successful
SpiceDB connection is established — check pod logs for successful CAS client initialization
Kafka topics ai.flowx.license.usage.v1 and ai.flowx.organization.events.v1 exist and the service can consume from them

​
Ingress and CORS

The License service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

​
Service route

Host groupExternal pathBackend receives
admin/license/
The path is set through services.license.ingress.admin.path (or services.license.gateway.admin.paths) in the chart values.

​
CORS configuration

Environment VariableDescriptionDefault Value
APPLICATION_CORS_ALLOW_ORIGINComma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer domain that issues browser requests against License.-
Allowed methods, allowed headers (including Authorization, Content-Type, Fx-Workspace-Id), and credential handling are baked into the service’s application.yaml with safe defaults. Override these only if you have a non-standard requirement. For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the ingress configuration guide.

​
Troubleshooting

Symptoms: Service fails to start with database connection errors.Solutions:
  1. Verify the license database exists in PostgreSQL
  2. Check that the database user has appropriate permissions
  3. Ensure network connectivity between the pod and PostgreSQL service
  4. Verify the JDBC URL format is correct
Symptoms: Authorization errors or service fails to initialize CAS client.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
  4. Review pod logs for specific CAS client error messages
Symptoms: License usage events or organization events not being processed.Solutions:
  1. Verify Kafka bootstrap servers are reachable
  2. Check that the ai.flowx.license.usage.v1 and ai.flowx.organization.events.v1 topics exist
  3. Ensure the service has consumer permissions on the topics
  4. Check consumer group offsets for lag
Symptoms: 401/403 errors when communicating with other FlowX services.Solutions:
  1. Verify the Keycloak service account flowx-license-sa is properly configured
  2. Check that client secrets match between configuration and Keycloak
  3. Ensure the service account has the view-users client role assigned
  4. Verify the service account realm UUID is correct

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

Access Management

Configure roles and access rights

SpiceDB Configuration

Fine-grained authorization setup

IAM Configuration

Identity and access management setup including License service account
Last modified on June 2, 2026