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

> Deploy-time environment variables for Lerian SPI — runtime, BACEN SPI/DICT connectivity, message signing and certificates, PII encryption, persistence, streaming, and security.

Lerian SPI is Lerian's native messaging integration for Pix, reaching BACEN's instant-payment system (SPI) and the DICT directory over the RSFN. It is a single deployable with three cooperating surfaces — the SPI settlement core, the DICT client, and BR Code — so its variable set is broad. All variables are set at deploy time and require a service restart. For the knobs that behave the same across every Lerian Go service — deployment posture, datastores, multi-tenancy, telemetry, streaming — see [BYOC configuration essentials](/en/reference/byoc-configuration).

In the tables below, **Required** marks a variable that must be set (globally, or under the condition named). `—` means no default.

<Note>
  Most BACEN-facing variables are namespaced by surface: `BACEN_SPI_*` for the SPI settlement transport, `BACEN_DICT_*` for the DICT client, `BACEN_BRCODE_*` for BR Code JOSE signing, and `BACEN_ICOM_*` for the inbound long-poll channel.
</Note>

## Runtime and server

| Variable                       | Description                                                                                  | Default                             | Required |
| ------------------------------ | -------------------------------------------------------------------------------------------- | ----------------------------------- | -------- |
| `ENV_NAME`                     | Runtime environment label. Production arms stricter security gates.                          | `development`                       | No       |
| `LOG_LEVEL`                    | Log verbosity (`debug`, `info`, `warn`, `error`).                                            | `info`                              | No       |
| `SERVER_ADDRESS`               | Main HTTP listen address (`host:port`). Liveness, readiness, and systemplane bind this port. | `:8080`                             | No       |
| `HTTP_BODY_LIMIT_BYTES`        | Maximum request body size in bytes.                                                          | `1048576`                           | No       |
| `PUBLIC_BASE_URL`              | Externally reachable base URL of the service, used to build absolute callback URLs.          | —                                   | No       |
| `ACCESS_CONTROL_ALLOW_ORIGIN`  | Allowed CORS origins.                                                                        | `http://localhost:3000`             | No       |
| `ACCESS_CONTROL_ALLOW_METHODS` | Allowed CORS methods.                                                                        | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | No       |
| `ACCESS_CONTROL_ALLOW_HEADERS` | Allowed CORS request headers.                                                                | (standard set)                      | No       |
| `TRUSTED_PROXIES`              | Comma-separated proxy IPs/CIDRs trusted to set the real client IP.                           | —                                   | No       |
| `SERVER_TLS_CERT_FILE`         | Path to the server TLS certificate. Set together with the key file.                          | —                                   | No       |
| `SERVER_TLS_KEY_FILE`          | Path to the server TLS private key. Sensitive.                                               | —                                   | No       |
| `SERVER_TLS_CLIENT_CA_FILE`    | CA file for verifying client certificates (mutual TLS).                                      | —                                   | No       |
| `TLS_TERMINATED_UPSTREAM`      | Set `true` when TLS is terminated by a load balancer or reverse proxy.                       | `false`                             | No       |

## Authentication

Lerian SPI authorizes protected routes — including the systemplane admin API — through Access Manager.

| Variable                       | Description                                                                                        | Default | Required   |
| ------------------------------ | -------------------------------------------------------------------------------------------------- | ------- | ---------- |
| `AUTH_ENABLED`                 | Require Access Manager authentication on protected routes. Enable in production.                   | `false` | No         |
| `PLUGIN_AUTH_ADDRESS`          | Access Manager service address.                                                                    | —       | If enabled |
| `AUTH_TRUST_UPSTREAM_METADATA` | Trust identity metadata forwarded by an upstream proxy. Leave `false` unless the proxy is trusted. | `false` | No         |

## BACEN callback (inbound from SPI)

| Variable                             | Description                                                                       | Default | Required |
| ------------------------------------ | --------------------------------------------------------------------------------- | ------- | -------- |
| `BACEN_CALLBACK_TRUSTED_PROXY_CIDRS` | CIDRs trusted as the source of BACEN callbacks.                                   | —       | No       |
| `BACEN_CALLBACK_MTLS_HEADER_SECRET`  | Shared secret proving the upstream terminated the callback mutual-TLS. Sensitive. | —       | No       |

## SPI settlement transport (`BACEN_SPI_*`)

Connection to BACEN's SPI settlement endpoint over the RSFN, with an optional secondary endpoint and the archive (ARQ) endpoint.

| Variable                                     | Description                                                   | Default                 | Required         |
| -------------------------------------------- | ------------------------------------------------------------- | ----------------------- | ---------------- |
| `BACEN_SPI_ENDPOINT`                         | Primary SPI endpoint URL.                                     | `http://localhost:9900` | Yes (live SPI)   |
| `BACEN_SPI_SECONDARY_ENDPOINT`               | Secondary SPI endpoint URL for failover.                      | —                       | No               |
| `BACEN_ARQ_ENDPOINT`                         | ARQ (archive/batch) endpoint URL.                             | —                       | No               |
| `BACEN_SPI_PARTICIPANT_ISPB`                 | The participant's ISPB for the SPI surface.                   | —                       | Yes (live SPI)   |
| `BACEN_SPI_ALLOWED_ENDPOINT_HOSTS`           | Allow-list of hosts the SPI client may reach (SSRF guard).    | —                       | No               |
| `BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS` | Allow-list for the secondary endpoint.                        | —                       | No               |
| `BACEN_ARQ_ALLOWED_ENDPOINT_HOSTS`           | Allow-list for the ARQ endpoint.                              | —                       | No               |
| `BACEN_SPI_TIMEOUT_SEC`                      | Request timeout (seconds).                                    | `30`                    | No               |
| `BACEN_SPI_INITIATION_TIMEOUT_MS`            | Payment-initiation timeout (milliseconds).                    | `150`                   | No               |
| `BACEN_SPI_INBOUND_CALLBACK_TIMEOUT_MS`      | Inbound-callback processing timeout (milliseconds).           | `250`                   | No               |
| `BACEN_SPI_RETRY_ATTEMPTS`                   | Retry attempts on transport failure.                          | `3`                     | No               |
| `BACEN_SPI_RETRY_INITIAL_BACKOFF_MS`         | Initial retry backoff (milliseconds).                         | `500`                   | No               |
| `BACEN_SPI_RETRY_MAX_BACKOFF_MS`             | Maximum retry backoff (milliseconds).                         | `5000`                  | No               |
| `BACEN_SPI_OUTBOUND_QUOTA_ENABLED`           | Enable client-side outbound rate quota.                       | `false`                 | No               |
| `BACEN_SPI_OUTBOUND_QUOTA_LIMIT`             | Sustained outbound quota (requests).                          | —                       | If quota enabled |
| `BACEN_SPI_OUTBOUND_QUOTA_BURST`             | Burst allowance above the quota.                              | —                       | If quota enabled |
| `BACEN_SPI_CATALOGUE_VERSION`                | BACEN SPI message-catalogue version.                          | `5.12.1`                | No               |
| `BACEN_SPI_XSD_DIR`                          | Directory of the bundled BACEN XSD schemas for the catalogue. | Bundled path            | No               |
| `BACEN_SPI_CATALOGUE_ROOT`                   | Override root for the message catalogue.                      | —                       | No               |
| `BACEN_SPI_INTERNAL_CALLBACK_SECRET`         | Shared secret for the internal callback path. Sensitive.      | —                       | No               |

### mutual TLS to BACEN

The `BACEN_TLS_*` files back the mutual-TLS channel to BACEN and are shared by the SPI and DICT clients.

| Variable              | Description                                          | Default | Required   |
| --------------------- | ---------------------------------------------------- | ------- | ---------- |
| `BACEN_TLS_CERT_FILE` | Client certificate presented to BACEN.               | —       | Yes (live) |
| `BACEN_TLS_KEY_FILE`  | Client private key. Sensitive.                       | —       | Yes (live) |
| `BACEN_TLS_CA_FILE`   | CA bundle used to verify BACEN's server certificate. | —       | Yes (live) |

## Message signing and certificates

SPI messages are digitally signed. Pick a custody backend with `BACEN_SPI_SIGNER_KIND`.

| Variable                               | Description                                                                                 | Default | Required    |
| -------------------------------------- | ------------------------------------------------------------------------------------------- | ------- | ----------- |
| `BACEN_SPI_SIGNER_KIND`                | Signing custody backend: `file`, `pkcs11`, or `kmip`. Use a hardware backend in production. | `file`  | No          |
| `BACEN_SPI_SIGNER_COMMON_NAME`         | Expected common name of the signing certificate.                                            | —       | No          |
| `BACEN_SPI_SIGNING_CERT_FILE`          | Path to the signing certificate.                                                            | —       | No          |
| `BACEN_SPI_INBOUND_SIGNER_COMMON_NAME` | Expected common name of the signer on inbound messages.                                     | —       | No          |
| `CERT_READINESS_MIN_DAYS`              | Minimum days-to-expiry before the certificate readiness check reports degraded.             | `14`    | No          |
| `BACEN_SPI_PKCS11_MODULE_PATH`         | PKCS#11 module library path.                                                                | —       | If `pkcs11` |
| `BACEN_SPI_PKCS11_TOKEN_LABEL`         | PKCS#11 token label.                                                                        | —       | If `pkcs11` |
| `BACEN_SPI_PKCS11_PIN_FILE`            | Path to a file holding the token PIN. Sensitive.                                            | —       | If `pkcs11` |
| `BACEN_SPI_PKCS11_KEY_LABEL`           | Signing-key label on the token.                                                             | —       | If `pkcs11` |
| `BACEN_SPI_KMIP_BASE_URL`              | KMIP service base URL.                                                                      | —       | If `kmip`   |
| `BACEN_SPI_KMIP_VHSM`                  | Virtual HSM identifier.                                                                     | —       | If `kmip`   |
| `BACEN_SPI_KMIP_CRYPTO_USER`           | KMIP crypto user.                                                                           | —       | If `kmip`   |
| `BACEN_SPI_KMIP_CRYPTO_USER_TOKEN`     | KMIP crypto-user token. Sensitive.                                                          | —       | If `kmip`   |
| `BACEN_SPI_KMIP_SIGN_PRIVATE_KEY_UID`  | UID of the signing private key.                                                             | —       | If `kmip`   |
| `BACEN_SPI_KMIP_SIGN_PUBLIC_KEY_UID`   | UID of the signing public key.                                                              | —       | If `kmip`   |
| `BACEN_SPI_KMIP_DIGEST_INFO_PREFIX`    | Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.                              | `false` | No          |

### Certificate validation (OCSP/CRL)

| Variable                           | Description                                           | Default     | Required |
| ---------------------------------- | ----------------------------------------------------- | ----------- | -------- |
| `BACEN_SPI_OCSP_MODE`              | Certificate revocation-check mode (e.g. `soft_fail`). | `soft_fail` | No       |
| `BACEN_SPI_OCSP_TIMEOUT_MS`        | OCSP request timeout (milliseconds).                  | `3000`      | No       |
| `BACEN_SPI_OCSP_CACHE_TTL_CAP_SEC` | Cap on cached OCSP response TTL (seconds).            | `3600`      | No       |
| `BACEN_SPI_OCSP_CRL_CACHE_TTL_SEC` | CRL cache TTL (seconds).                              | `3600`      | No       |

### Payload resolver

Controls how large SPI payloads are stored and referenced.

| Variable                                         | Description                                        | Default     | Required |
| ------------------------------------------------ | -------------------------------------------------- | ----------- | -------- |
| `BACEN_SPI_PAYLOAD_RESOLVER_KIND`                | Payload storage backend (e.g. `in_memory`).        | `in_memory` | No       |
| `BACEN_SPI_PAYLOAD_RESOLVER_IN_MEMORY_MAX_BYTES` | Max bytes held by the in-memory resolver.          | `134217728` | No       |
| `BACEN_SPI_PAYLOAD_RESOLVER_TTL_SEC`             | Retention TTL for resolved payloads (seconds).     | `86400`     | No       |
| `BACEN_SPI_PAYLOAD_RESOLVER_ENCRYPTION_KEY`      | AES key for encrypting stored payloads. Sensitive. | —           | No       |

## Inbound channel (`BACEN_ICOM_*`)

Long-poll channel for messages BACEN pushes back to the participant.

| Variable                                | Description                               | Default | Required |
| --------------------------------------- | ----------------------------------------- | ------- | -------- |
| `BACEN_ICOM_BASE_URL`                   | Inbound channel base URL.                 | —       | No       |
| `BACEN_ICOM_ISPB`                       | Participant ISPB for the inbound channel. | —       | No       |
| `BACEN_ICOM_CONSUMER_ENABLED`           | Enable the primary inbound consumer.      | `false` | No       |
| `BACEN_ICOM_SECONDARY_CONSUMER_ENABLED` | Enable the secondary inbound consumer.    | `false` | No       |
| `BACEN_ICOM_LONGPOLL_TIMEOUT_MS`        | Long-poll wait timeout (milliseconds).    | `90000` | No       |

## DICT client (`BACEN_DICT_*`)

Client for BACEN's Pix key directory (DICT), including the anti-fraud (NP) endpoint.

| Variable                               | Description                                                     | Default                 | Required        |
| -------------------------------------- | --------------------------------------------------------------- | ----------------------- | --------------- |
| `BACEN_DICT_ENDPOINT`                  | DICT endpoint URL.                                              | `http://localhost:9900` | Yes (live DICT) |
| `BACEN_DICT_PARTICIPANT_ISPB`          | Participant ISPB for the DICT surface.                          | —                       | Yes (live DICT) |
| `BACEN_DICT_ALLOWED_ENDPOINT_HOSTS`    | Allow-list of hosts the DICT client may reach.                  | —                       | No              |
| `BACEN_DICT_TIMEOUT_SEC`               | DICT request timeout (seconds).                                 | `10`                    | No              |
| `BACEN_DICT_NP_ENDPOINT`               | Anti-fraud (NP) endpoint URL.                                   | —                       | No              |
| `BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS` | Allow-list for the NP endpoint.                                 | —                       | No              |
| `BACEN_DICT_SIGNER_KIND`               | DICT signing custody backend: `file`, `pkcs11`, or `kmip`.      | `file`                  | No              |
| `BACEN_DICT_SIGNING_CERT_FILE`         | Path to the DICT signing certificate.                           | —                       | No              |
| `BACEN_DICT_SIGNING_KEY_FILE`          | Path to the DICT signing private key (file backend). Sensitive. | —                       | If `file`       |
| `BACEN_DICT_VERIFY_CERT_FILE`          | Certificate used to verify DICT responses.                      | —                       | No              |
| `BACEN_DICT_PKCS11_MODULE_PATH`        | PKCS#11 module path.                                            | —                       | If `pkcs11`     |
| `BACEN_DICT_PKCS11_TOKEN_LABEL`        | PKCS#11 token label.                                            | —                       | If `pkcs11`     |
| `BACEN_DICT_PKCS11_PIN_FILE`           | Path to the token PIN file. Sensitive.                          | —                       | If `pkcs11`     |
| `BACEN_DICT_PKCS11_KEY_LABEL`          | Signing-key label on the token.                                 | —                       | If `pkcs11`     |
| `BACEN_DICT_KMIP_BASE_URL`             | KMIP service base URL.                                          | —                       | If `kmip`       |
| `BACEN_DICT_KMIP_VHSM`                 | Virtual HSM identifier.                                         | —                       | If `kmip`       |
| `BACEN_DICT_KMIP_CRYPTO_USER`          | KMIP crypto user.                                               | —                       | If `kmip`       |
| `BACEN_DICT_KMIP_CRYPTO_USER_TOKEN`    | KMIP crypto-user token. Sensitive.                              | —                       | If `kmip`       |
| `BACEN_DICT_KMIP_SIGN_PRIVATE_KEY_UID` | UID of the signing private key.                                 | —                       | If `kmip`       |
| `BACEN_DICT_KMIP_SIGN_PUBLIC_KEY_UID`  | UID of the signing public key.                                  | —                       | If `kmip`       |
| `BACEN_DICT_KMIP_DIGEST_INFO_PREFIX`   | Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.  | `false`                 | No              |
| `BACEN_DICT_INTENT_ENCRYPTION_KEY`     | AES key for encrypting stored DICT claim intents. Sensitive.    | —                       | No              |

## BR Code JOSE signing (`BACEN_BRCODE_JOSE_*`)

Signs dynamic BR Code payloads (JWS).

| Variable                                      | Description                                                     | Default | Required    |
| --------------------------------------------- | --------------------------------------------------------------- | ------- | ----------- |
| `BACEN_BRCODE_JOSE_SIGNER_KIND`               | JOSE signing custody backend: `file`, `pkcs11`, or `kmip`.      | —       | No          |
| `BACEN_BRCODE_JOSE_SIGNING_CERT_FILE`         | Path to the JOSE signing certificate.                           | —       | No          |
| `BACEN_BRCODE_JOSE_SIGNING_KEY_FILE`          | Path to the JOSE signing private key (file backend). Sensitive. | —       | If `file`   |
| `BACEN_BRCODE_JOSE_KID`                       | JWS key identifier (`kid`) header value.                        | —       | No          |
| `BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH`        | PKCS#11 module path.                                            | —       | If `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL`        | PKCS#11 token label.                                            | —       | If `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_PIN_FILE`           | Path to the token PIN file. Sensitive.                          | —       | If `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL`          | Signing-key label on the token.                                 | —       | If `pkcs11` |
| `BACEN_BRCODE_JOSE_KMIP_BASE_URL`             | KMIP service base URL.                                          | —       | If `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_VHSM`                 | Virtual HSM identifier.                                         | —       | If `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER`          | KMIP crypto user.                                               | —       | If `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN`    | KMIP crypto-user token. Sensitive.                              | —       | If `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID` | UID of the signing private key.                                 | —       | If `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID`  | UID of the signing public key.                                  | —       | If `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX`   | Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.  | `false` | No          |

## PII encryption and hashing

<Warning>
  Every variable below is sensitive key or pepper material for encrypting and blind-indexing personal data at rest. Never commit or log a value; inject it at deploy time through your secret manager. Rotating a pepper or key requires a planned re-index/re-encryption.
</Warning>

| Variable                            | Description                                         | Default | Required |
| ----------------------------------- | --------------------------------------------------- | ------- | -------- |
| `DICT_KEY_PII_ENCRYPTION_KEY`       | AES key for DICT key-holder PII. Sensitive.         | —       | No       |
| `DICT_KEY_BLIND_INDEX_PEPPER`       | Pepper for blind-indexing DICT key PII. Sensitive.  | —       | No       |
| `DICT_AUDIT_HASH_PEPPER`            | Pepper for DICT audit-record hashing. Sensitive.    | —       | No       |
| `AUDIT_HASH_PEPPER`                 | Legacy audit-hash pepper. Sensitive.                | —       | No       |
| `SPI_RESPONSIBLES_ENCRYPTION_KEY`   | AES key for responsible-party PII. Sensitive.       | —       | No       |
| `SPI_OPERATIONS_PII_ENCRYPTION_KEY` | AES key for operation PII. Sensitive.               | —       | No       |
| `SPI_OPERATIONS_BLIND_INDEX_PEPPER` | Pepper for blind-indexing operation PII. Sensitive. | —       | No       |
| `BRCODE_PII_ENCRYPTION_KEY`         | AES key for BR Code PII. Sensitive.                 | —       | No       |
| `BRCODE_PII_BLIND_INDEX_PEPPER`     | Pepper for blind-indexing BR Code PII. Sensitive.   | —       | No       |

## PostgreSQL

| Variable                           | Description                                                                | Default     | Required      |
| ---------------------------------- | -------------------------------------------------------------------------- | ----------- | ------------- |
| `POSTGRES_HOST`                    | Primary PostgreSQL host.                                                   | `localhost` | Yes           |
| `POSTGRES_PORT`                    | Primary PostgreSQL port.                                                   | `5432`      | No            |
| `POSTGRES_USER`                    | Database user.                                                             | —           | Yes           |
| `POSTGRES_PASSWORD`                | Database password. Sensitive.                                              | —           | In production |
| `POSTGRES_DB`                      | Database name.                                                             | —           | Yes           |
| `POSTGRES_SSLMODE`                 | libpq TLS mode. Use `require` or stronger in production.                   | `disable`   | No            |
| `POSTGRES_MAX_OPEN_CONNS`          | Maximum open connections.                                                  | `25`        | No            |
| `POSTGRES_MAX_IDLE_CONNS`          | Maximum idle connections.                                                  | `5`         | No            |
| `POSTGRES_CONN_MAX_LIFETIME_MINS`  | Connection max lifetime (minutes).                                         | `30`        | No            |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | Connection max idle time (minutes).                                        | `5`         | No            |
| `POSTGRES_CONNECT_TIMEOUT_SEC`     | Connection timeout (seconds).                                              | `10`        | No            |
| `POSTGRES_REPLICA_HOST`            | Optional read-replica host. Other replica fields fall back to the primary. | —           | No            |
| `POSTGRES_REPLICA_PORT`            | Replica port.                                                              | —           | No            |
| `POSTGRES_REPLICA_USER`            | Replica user.                                                              | —           | No            |
| `POSTGRES_REPLICA_PASSWORD`        | Replica password. Sensitive.                                               | —           | No            |
| `POSTGRES_REPLICA_DB`              | Replica database name.                                                     | —           | No            |
| `POSTGRES_REPLICA_SSLMODE`         | Replica TLS mode.                                                          | —           | No            |

## Redis

| Variable                 | Description                               | Default          | Required |
| ------------------------ | ----------------------------------------- | ---------------- | -------- |
| `REDIS_HOST`             | Redis host and port.                      | `localhost:6379` | No       |
| `REDIS_MASTER_NAME`      | Sentinel master name (if using Sentinel). | —                | No       |
| `REDIS_PASSWORD`         | Redis password. Sensitive.                | —                | No       |
| `REDIS_DB`               | Redis database number.                    | `0`              | No       |
| `REDIS_PROTOCOL`         | Redis protocol version (2 or 3).          | `3`              | No       |
| `REDIS_TLS`              | Enable TLS to Redis.                      | `false`          | No       |
| `REDIS_CA_CERT`          | CA certificate for Redis TLS.             | —                | No       |
| `REDIS_POOL_SIZE`        | Connection pool size.                     | `10`             | No       |
| `REDIS_MIN_IDLE_CONNS`   | Minimum idle connections.                 | `2`              | No       |
| `REDIS_READ_TIMEOUT_MS`  | Read timeout (milliseconds).              | `3000`           | No       |
| `REDIS_WRITE_TIMEOUT_MS` | Write timeout (milliseconds).             | `3000`           | No       |
| `REDIS_DIAL_TIMEOUT_MS`  | Dial timeout (milliseconds).              | `5000`           | No       |

## Outbox and streaming

Lerian SPI publishes events through a transactional outbox and a lib-streaming producer, and consumes settlement events for BR Code. The streaming variables (`STREAMING_ENABLED`, `STREAMING_BROKERS`, `STREAMING_CLOUDEVENTS_SOURCE`, `STREAMING_COMPRESSION`, `STREAMING_REQUIRED_ACKS`, `STREAMING_EVENT_POLICIES`) follow the shared backbone — see [Streaming and outbox](/en/reference/byoc-configuration#streaming-and-outbox). `STREAMING_BROKERS` is required whenever `STREAMING_ENABLED=true`.

| Variable                               | Description                                                      | Default  | Required |
| -------------------------------------- | ---------------------------------------------------------------- | -------- | -------- |
| `OUTBOX_ENABLED`                       | Enable the transactional outbox dispatcher.                      | `true`   | No       |
| `OUTBOX_DISPATCH_INTERVAL_MS`          | Interval between dispatch cycles (milliseconds).                 | `2000`   | No       |
| `OUTBOX_BATCH_SIZE`                    | Rows drained per dispatch cycle.                                 | `50`     | No       |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS`         | Dispatch attempts before an event is parked.                     | `10`     | No       |
| `OUTBOX_PROCESSING_TIMEOUT_MS`         | Per-batch processing timeout (milliseconds).                     | `600000` | No       |
| `OUTBOX_RETRY_WINDOW_MS`               | Retry window before a stuck row is reclaimed (milliseconds).     | `300000` | No       |
| `BRCODE_SETTLEMENT_CONSUMER_TOPIC`     | Topic the BR Code settlement consumer reads. Set per deployment. | —        | No       |
| `BRCODE_SETTLEMENT_CONSUMER_GROUP`     | Consumer group for BR Code settlement.                           | —        | No       |
| `BRCODE_SETTLEMENT_CONSUMER_CLIENT_ID` | Client ID presented to the broker by the settlement consumer.    | —        | No       |

## Schedulers

Background jobs, each independently gated. All default off.

| Variable                                            | Description                                | Default | Required |
| --------------------------------------------------- | ------------------------------------------ | ------- | -------- |
| `SCHEDULER_ENABLED`                                 | Master switch for the scheduler subsystem. | `false` | No       |
| `SCHEDULER_MED_DEADLINE_ENABLED`                    | Run the MED (special return) deadline job. | `false` | No       |
| `SCHEDULER_QUOTA_RESET_ENABLED`                     | Run the outbound-quota reset job.          | `false` | No       |
| `SCHEDULER_CLAIM_DEADLINE_ENABLED`                  | Run the DICT claim-deadline job.           | `false` | No       |
| `SCHEDULER_DICT_RECONCILIATION_INCREMENTAL_ENABLED` | Run incremental DICT reconciliation.       | `false` | No       |
| `SCHEDULER_DICT_RECONCILIATION_FULL_ENABLED`        | Run full DICT reconciliation.              | `false` | No       |
| `SCHEDULER_DICT_AUDIT_RETENTION_ENABLED`            | Run the DICT audit-retention job.          | `false` | No       |
| `SCHEDULER_INBOUND_DISCOVERY_ENABLED`               | Run the inbound-message discovery job.     | `false` | No       |
| `SCHEDULER_APPROVAL_EXPIRY_ENABLED`                 | Run the approval-expiry sweep.             | `false` | No       |
| `SCHEDULER_PORTABILITY_DEADLINE_ENABLED`            | Run the portability-deadline job.          | `false` | No       |

## Rate limiting, idempotency, and connectivity

| Variable                       | Description                                                           | Default | Required |
| ------------------------------ | --------------------------------------------------------------------- | ------- | -------- |
| `RATE_LIMIT_ENABLED`           | Enable request rate limiting.                                         | `true`  | No       |
| `RATE_LIMIT_MAX`               | Maximum requests per window.                                          | `100`   | No       |
| `RATE_LIMIT_EXPIRY_SEC`        | Rate-limit window (seconds).                                          | `60`    | No       |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | How long (seconds) an idempotency key is retained.                    | `86400` | No       |
| `INFRA_CONNECT_TIMEOUT_SEC`    | Connect timeout for infrastructure dependencies at startup (seconds). | `30`    | No       |

## Systemplane and runtime configuration

| Variable              | Description                                                                                                                                                                                                                                                         | Default | Required |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| `SYSTEMPLANE_ENABLED` | Enable the systemplane runtime-configuration admin API, mounted at `/v1/system` on the main port. When `false`, the service runs in env-only mode with no admin plane. **SPI defaults this on** — unlike most Lerian services, where systemplane is off by default. | `true`  | No       |

See [Systemplane](/en/reference/systemplane/overview) for the API, namespaces, and required permissions.

## Observability

| Variable                               | Description                                                            | Default          | Required             |
| -------------------------------------- | ---------------------------------------------------------------------- | ---------------- | -------------------- |
| `ENABLE_TELEMETRY`                     | Enable OpenTelemetry tracing and metrics.                              | `false`          | No                   |
| `TELEMETRY_REQUIRED`                   | Fail startup if telemetry cannot initialize.                           | `false`          | No                   |
| `OTEL_EXPORTER_OTLP_ENDPOINT`          | OTLP collector endpoint.                                               | `localhost:4317` | If telemetry enabled |
| `OTEL_RESOURCE_SERVICE_NAME`           | Service name attached to exported telemetry.                           | Service default  | No                   |
| `OTEL_RESOURCE_SERVICE_VERSION`        | Service version label.                                                 | Per release      | No                   |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Deployment environment label.                                          | `development`    | No                   |
| `OTEL_LIBRARY_NAME`                    | Instrumentation library name.                                          | Service default  | No                   |
| `METRICS_PROMETHEUS_ENABLED`           | Expose a dedicated Prometheus scrape endpoint.                         | `false`          | No                   |
| `METRICS_PROMETHEUS_ADDRESS`           | Listen address for the Prometheus endpoint. Binds loopback by default. | `127.0.0.1:9090` | No                   |

## Documentation

| Variable          | Description                                                       | Default | Required |
| ----------------- | ----------------------------------------------------------------- | ------- | -------- |
| `SWAGGER_ENABLED` | Serve the OpenAPI spec and API docs UI. Forced off in production. | `false` | No       |

## Health and readiness

Lerian SPI exposes `GET /health` (liveness), `GET /readyz` (readiness), and `GET /version` on the main HTTP port; `/metrics` runs on its own listener when enabled. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.