> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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 |