Environment variables

Reference for the Flowker environment variables covering server, scheduler, deployment, authentication, MongoDB, schema registry, secrets, and multi-tenant settings.

This reference lists the environment variables that configure Flowker.

The Default column lists only the values Flowker applies in code when a variable is not set. A dash means Flowker applies no fallback: set the variable explicitly, using the recommended value in the description. The Required column marks the variables that stop the server from starting when they are missing.

Flowker ships two binaries. The API binary serves the HTTP API. The worker binary runs the scheduler that fires schedule-triggered workflows and serves only /health and /readyz. Variables that apply to one binary say so.

Server

Variable	Description	Default	Required
ENV_NAME	Environment name. Set one of production, staging, uat, development, or local — any other value, including an empty one, stops the server from starting. production turns on the production guards: request authentication, XSD schema authentication, and OpenAPI schema authentication must all be enabled or the server refuses to start. Recommended: production in production, development elsewhere.	—	Yes
SERVER_ADDRESS	Listen address of the API binary. When empty, Fiber binds all interfaces on an OS-assigned ephemeral port; set it explicitly (recommended: :4021) for a predictable address.	—	No
WORKER_SERVER_ADDRESS	Listen address of the worker binary’s /health and /readyz app. Must differ from SERVER_ADDRESS so both binaries can run on the same host.	:4022	No
VERSION	Version string reported by /readyz.	dev	No
CORS_ALLOWED_ORIGINS	Comma-separated list of allowed CORS origins. Empty means no cross-origin access is allowed (restrictive default).	—	No
TRUSTED_PROXIES	Comma-separated CIDR ranges of trusted proxies (your load balancer/ingress subnets). When set, X-Forwarded-For is trusted only from these hops, so Flowker resolves the real client IP — including the IP forwarded to Access Manager for IP-allowlist checks. Entries must be CIDR notation; a bare IP fails startup. Empty leaves the feature off.	—	No

Deployment

Variable	Description	Default	Required
DEPLOYMENT_MODE	Deployment flavor: local, byoc, or saas. In saas, Flowker validates TLS for a non-empty static MONGO_URI; multi-tenant MongoDB connections are resolved later and are not TLS-validated at bootstrap. Fixture providers are exposed when DEPLOYMENT_MODE resolves to local after trimming whitespace and case-insensitive matching, provided the environment is not production. /readyz reports local when the variable is unset. Recommended: byoc or saas outside a developer workstation.	—	No

Authentication

Variable	Description	Default	Required
PLUGIN_AUTH_ENABLED	Enable Access Manager plugin authentication. When false, the workflow, webhook, and management routes do not require authentication (local development only). With a production ENV_NAME, false stops the server from starting.	false	No
PLUGIN_AUTH_ADDRESS	Address of the Access Manager service. The machine-to-machine token endpoint is derived from it by appending /v1/login/oauth/access_token.	—	Yes (if PLUGIN_AUTH_ENABLED=true)
XSD_SCHEMAS_AUTH_ENABLED	Require authentication on the /v1/xsd-schemas routes. An unset or unrecognized value resolves to true. With a production ENV_NAME, false stops the server from starting.	true	No
OPENAPI_SCHEMAS_AUTH_ENABLED	Require authentication on the /v1/openapi-schemas routes. An unset or unrecognized value resolves to true. With a production ENV_NAME, false stops the server from starting.	true	No

Database (MongoDB)

Variable	Description	Default	Required
MONGO_URI	MongoDB connection URI. In multi-tenant mode no static pool is opened and per-tenant connections come from Tenant Manager instead.	—	Yes (single-tenant mode)
MONGO_DB_NAME	MongoDB database name. Recommended: flowker.	—	Yes (single-tenant mode)
MONGO_TLS_CA_CERT	Base64-encoded PEM CA certificate for TLS connections (e.g., AWS DocumentDB)	—	No

Scheduler

The scheduler fires schedule-triggered workflows. It runs in the worker binary and connects through its own Redis settings, separate from the multi-tenant Redis settings. Nothing enforces the separation at startup: point the scheduler at its own Redis instance, or at least at a logical database index that tenant lifecycle events do not use.

Variable	Description	Default	Required
SCHEDULER_ENABLED	Kill-switch for the scheduler. An unset or unrecognized value resolves to true; any valid boolean value that resolves to false (for example, false, 0, or f) disables it. The worker binary refuses to start while it is false.	true	No
SCHEDULER_REDIS_HOST	Host of the dedicated scheduler Redis. The scheduler queue lives here, so set it wherever the scheduler is enabled: with no host, the worker binary does not start and no scheduled workflow fires.	—	Yes (if SCHEDULER_ENABLED=true)
SCHEDULER_REDIS_PORT	Port of the scheduler Redis	6379	No
SCHEDULER_REDIS_PASSWORD	Password of the scheduler Redis. Required only when a worker starts an enabled scheduler with DEPLOYMENT_MODE=saas; API-only startup does not validate this setting.	—	Yes (worker; if SCHEDULER_ENABLED=true and DEPLOYMENT_MODE=saas)
SCHEDULER_REDIS_TLS	Enable TLS for the scheduler Redis connection. Set true in production and point the scheduler at a TLS-terminating Redis.	false	No
SCHEDULER_REDIS_DB	Logical Redis database index for the queue. When the scheduler shares a Redis instance with tenant lifecycle events, set a distinct index here; both default to 0.	0	No
SCHEDULER_CONCURRENCY	Worker concurrency cap for the scheduler consume server. A non-positive value resolves to 10.	10	No

Lerian service URLs

Internal providers resolve their base URL from the environment, by the {PROVIDER}_BASE_URL convention, instead of from the stored provider configuration. Leave a variable empty to fall back to the value in the stored configuration document.

Variable	Description	Default	Required
MIDAZ_BASE_URL	Base URL for the ledger provider. Feeds both the transaction and the onboarding base URL.	—	No
TRACER_BASE_URL	Base URL for the tracer provider	—	No
CRM_BASE_URL	Base URL for the crm provider	—	No
FEES_BASE_URL	Base URL for the fees provider	—	No
IDENTITY_BASE_URL	Base URL for the identity provider	—	No
AUTH_BASE_URL	Base URL for the auth provider	—	No
OPENAPI_NATIVE_PROVIDERS	Comma-separated allowlist of native provider ids eligible for synthesis from their published OpenAPI spec. Empty makes every native provider eligible; a non-empty list narrows eligibility to the named ids.	—	No

Schema registry and XSD validation

Variable	Description	Default	Required
SCHEMA_REGISTRY_S3_BUCKET	S3 storage is optional for boot. If the bucket is empty, Flowker starts with a MongoDB metadata path, but XSD and OpenAPI schema-content operations fail at use time; configure a bucket for a functional schema registry.	—	No
SCHEMA_REGISTRY_S3_REGION	Pins the AWS region of the schema registry bucket. Empty resolves the region through the standard AWS SDK chain (AWS_REGION or shared config).	—	No
SCHEMA_REGISTRY_CACHE_TTL_SEC	TTL of the parsed-spec cache behind the native output-schema resolver (seconds). A published spec change is picked up on the next fetch whose ETag differs, regardless of the TTL.	300	No
XSD_VALIDATOR_URL	Base URL of the XSD validator sidecar (e.g. http://xsd-validator:8081). Leave it empty to run without XML schema validation.	—	No
XSD_VALIDATOR_ALLOW_INSECURE_HTTP	A trimmed, case-insensitive true enables cleartext http:// for XSD_VALIDATOR_URL; 1, t, and yes do not.	false	No

Secrets

Variable	Description	Default	Required
FLOWKER_SECRETS_BACKEND	Backend that resolves external integration credentials. tenant-manager selects the AWS Secrets Manager reader; unset disables secret resolution. Any other value stops the server from starting.	—	No
FLOWKER_SECRETS_CACHE_TTL_SEC	TTL of the in-memory secrets cache (seconds)	30	No
FLOWKER_SECRETS_APPLICATION_NAME	applicationName path segment used when reading credentials from the Tenant Manager store. It must match WORKOS_TM_SERVICE_NAME so the read path and the write path resolve the same service identity.	flowker	No

Tenant Manager token mint

Flowker mints a platform-scoped bearer token to call the Tenant Manager write endpoints. Token minting requires WORKOS_TM_TOKEN_URL, WORKOS_TM_CLIENT_ID, and WORKOS_TM_CLIENT_SECRET together. WORKOS_TM_SCOPE is optional, but a non-blank value requires those three credential variables. WORKOS_TM_SERVICE_NAME only overrides the service name. Leave the token URL, client ID, client secret, and scope unset to disable minting. A partial configuration stops the server from starting. The Tenant Manager base URL comes from MULTI_TENANT_URL.

Variable	Description	Default	Required
WORKOS_TM_TOKEN_URL	OAuth 2.0 token endpoint that issues the platform-scoped bearer	—	Yes (all three, or none)
WORKOS_TM_CLIENT_ID	Client id for the client_credentials grant	—	Yes (all three, or none)
WORKOS_TM_CLIENT_SECRET	Client secret for the client_credentials grant. Inject it through your secret manager; it is never logged.	—	Yes (all three, or none)
WORKOS_TM_SCOPE	Space-delimited scope requested with the grant. Setting it alone, without the three credentials, stops the server from starting.	—	No
WORKOS_TM_SERVICE_NAME	Flowker’s service name as the Tenant Manager knows it. It must match FLOWKER_SECRETS_APPLICATION_NAME.	flowker	No

Multi-tenant

When MULTI_TENANT_ENABLED=true, database connections are resolved per tenant through Tenant Manager. When false (default), Flowker runs in single-tenant mode with static connections.

Variable	Description	Default	Required
MULTI_TENANT_ENABLED	Enable per-tenant connection resolution	false	No
MULTI_TENANT_URL	Tenant Manager API URL	—	Yes (if MULTI_TENANT_ENABLED=true)
MULTI_TENANT_SERVICE_API_KEY	API key for the Tenant Manager settings endpoint	—	Yes (if MULTI_TENANT_ENABLED=true)
MULTI_TENANT_ALLOW_INSECURE_HTTP	Allow a cleartext http:// Tenant Manager URL. Never enable in production — credentials travel in plaintext.	false	No
MULTI_TENANT_REDIS_HOST	Redis host for tenant lifecycle events. In multi-tenant deployments, configure a reachable endpoint so cache invalidation, credential rotation, and connection updates reach Flowker. Omit it only when you accept no lifecycle-event delivery and a per-replica cache for compiled OpenAPI request validators.	—	No
MULTI_TENANT_REDIS_PORT	Redis port	6379	No
MULTI_TENANT_REDIS_PASSWORD	Redis password	—	No
MULTI_TENANT_REDIS_TLS	Enable TLS for the Redis connection	false	No
MULTI_TENANT_MAX_TENANT_POOLS	Soft limit on cached per-tenant connection pools. Unset leaves the pool count unlimited. Recommended: 100.	—	No
MULTI_TENANT_IDLE_TIMEOUT_SEC	How long a tenant pool must stay idle before it becomes eligible for eviction (seconds). Recommended: 300.	—	No
MULTI_TENANT_TIMEOUT	Tenant Manager request timeout (seconds). Unset leaves the HTTP client without a timeout. Recommended: 30.	—	No
MULTI_TENANT_CACHE_TTL_SEC	Tenant settings cache TTL (seconds). A positive value applies to the local tenant cache and Tenant Manager client cache. When unset or non-positive, their defaults are 43200 seconds (12 hours) and 3600 seconds (1 hour), respectively. Recommended: 120.	43200 local / 3600 Tenant Manager client	No
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD	Consecutive failures that open the circuit. One value governs both the per-provider-configuration breaker and the Tenant Manager HTTP client breaker. Unset leaves the per-provider-configuration breaker at 20 and the Tenant Manager breaker inactive, so set it explicitly in multi-tenant deployments.	20 (per provider configuration)	No
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC	Circuit breaker recovery timeout (seconds)	30	No

Token cache

Bounds for the shared OAuth 2.0 token cache used by provider authentication (OIDC and OAuth2 token-endpoint flows).

Variable	Description	Default	Required
TOKEN_CACHE_MAX_TTL_SEC	Maximum time any cached token is trusted, regardless of the provider’s expires_in	3600	No
TOKEN_CACHE_JANITOR_INTERVAL_SEC	How often the background janitor evicts expired tokens (seconds)	300	No
TOKEN_CACHE_REFRESH_BUFFER_SEC	How long before expiry a cached token is refreshed proactively (seconds)	60	No
TOKEN_CACHE_TENANT_SCOPED_DISABLED	Opt out of tenant-scoped token caching. Tenant scoping is the default in multi-tenant mode; disabling it re-shares one cache across tenants.	false	No

Observability

Variable	Description	Default	Required
ENABLE_TELEMETRY	Enable OpenTelemetry instrumentation	false	No
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP exporter endpoint	—	Yes (if ENABLE_TELEMETRY=true)
OTEL_RESOURCE_SERVICE_NAME	Service name for telemetry. Recommended: flowker.	—	No
OTEL_RESOURCE_SERVICE_VERSION	Service version for telemetry	—	No
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT	Deployment environment label	—	No
OTEL_LIBRARY_NAME	Instrumentation library name. The logger requires it on every boot, including when ENABLE_TELEMETRY is false. Recommended: flowker.	—	Yes
SKIP_LIB_COMMONS_TELEMETRY	Skip commons library telemetry	false	No
LOG_LEVEL	Log level (debug, info, warn, error, dpanic, panic, or fatal; case-insensitive). Unset, the level follows ENV_NAME: development and local log at debug, every other value logs at info. An unrecognized level stops the server from starting.	—	No

Security

Variable	Description	Default	Required
SSRF_ALLOW_PRIVATE	Allow executor HTTP calls to private IPs. Only the exact string true enables it. Never enable in production.	false	No
ALLOW_INSECURE_TLS	Skip the TLS requirement on the shared infrastructure clients and log a warning instead. Accepts true, 1, yes, or on. Leave it unset in production so real TLS stays mandatory.	false	No
HTTP_MAX_BODY_BYTES	Cap on the request body sent to and the response body read from outbound provider HTTP calls (bytes). A zero or negative value resolves to the default.	10485760 (10 MiB)	No
FAULT_INJECTION_ENABLED	Enable fault injection for testing	false	No

Swagger

Variable	Description	Default	Required
SWAGGER_ENABLED	Serve the generated OpenAPI spec and docs UI at /openapi/openapi.json, /openapi/openapi.yaml, and /openapi/docs	false	No
SWAGGER_TITLE	Title of the docs UI page	—	No