Environment variables

Deploy-time environment variables for Lerian SPI: BACEN SPI/DICT connectivity, ISO 20022 signing certificates, PII encryption, persistence, and streaming.

Lerian SPI is Lerian’s native messaging integration for Pix. It reaches BACEN’s instant-payment system (SPI) and the DICT key directory over the RSFN. It ships four runtime binaries (spi, dict, brcode, and core), so its variable set is broad.

The service reads every variable at startup. A value that does not parse for its type, such as yes for a switch, stops startup. When systemplane is on (the default), it can override a subset at runtime without a restart. The rest of the variables need a restart to change. For the knobs that behave the same across every Lerian Go service (deployment posture, datastores, telemetry), see BYOC configuration essentials.

In the tables below, Required marks a variable you must set, always (Yes) or under the condition named. — means no default. The conditions use three terms:

• Live: the BACEN endpoint uses https. A local environment also accepts an http endpoint.
• Local environment: ENV_NAME is development, local, or test.
• Protected environment: ENV_NAME is production, prod, staging, stage, pre-prod, preprod, pre-production, or preproduction.

Most BACEN-facing variables carry a surface prefix: BACEN_SPI_* for the SPI settlement transport, BACEN_DICT_* for the DICT client, BACEN_BRCODE_JOSE_* for BR Code JOSE signing, and BACEN_ICOM_* for the inbound long-poll channel.

​

Runtime and server

Variable	Description	Default	Required
ENV_NAME	Runtime environment label. When unset, it resolves to development. An explicit none is invalid.	development	No
LOG_LEVEL	Log verbosity (debug, info, warn, error).	info	No
SERVER_ADDRESS	Main HTTP listen address (host:port or :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. It builds the BR Code payload links and the URL of the JWS key set. The systemplane key brcode.server/public_base_url overrides it at runtime.	—	In a protected environment or if BR Code JOSE is enabled
ACCESS_CONTROL_ALLOW_ORIGIN	Allowed CORS origins, comma-separated. Each entry is an exact scheme://host[:port] origin, written as a browser sends it: lowercase host, no default port, no path, no trailing slash. A wildcard, including *.domain, stops startup in every environment. A protected environment accepts only https origins, so it refuses the default.	http://localhost:3000	In a protected environment
TRUSTED_PROXIES	Comma-separated proxy IPs or CIDRs trusted to set the real client IP. Wildcards are refused.	—	In a protected environment with TLS_TERMINATED_UPSTREAM=true
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). Requires the certificate and key files.	—	No
TLS_TERMINATED_UPSTREAM	Set true when TLS is terminated by a load balancer or reverse proxy.	false	No

A protected environment requires the server certificate and key files, or TLS_TERMINATED_UPSTREAM=true.

​

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. Set true or false. A blank value stops startup. false starts only when ENV_NAME is development, develop, dev, local, or test, and never with DEPLOYMENT_MODE=saas.	—	Yes
PLUGIN_AUTH_ADDRESS	Access Manager service address. A protected environment requires https://.	—	If AUTH_ENABLED=true or in a protected environment
AUTH_REQUIRED	With true, protected routes answer 503 when authentication is off.	false	No
AUTH_TIMEOUT	Time limit for the Access Manager check of one request, retries included. Write it with a unit, such as 30s.	30s	No
AUTH_CACHE_TTL	Time that the rail keeps each Access Manager decision. Write it with a unit, such as 30s. A permission change can take this long to apply. When unset, the rail keeps no decisions.	—	No
AUTH_BREAKER_ENABLED	Turns on a circuit breaker for Access Manager calls. After 5 failed calls in a row, it stops the calls for 30 seconds. Meanwhile, the rail refuses each request that has no cached approval. Set true or false.	false	No
AUTH_RETRY_MAX	Maximum retries of an Access Manager call that fails without a decision. 0 turns off retries.	0	No
AUTH_JWT_VERIFY_CERT	One or more PEM RSA public keys or X.509 certificates, separated by newlines. With a loaded key, the rail checks the RS256 signature and the expiry of each bearer token, and answers 401 when the check fails. It takes precedence over AUTH_JWT_VERIFY_CERT_PATH.	—	No
AUTH_JWT_VERIFY_CERT_PATH	Path to a file with the same content. The rail reads it only when AUTH_JWT_VERIFY_CERT is empty.	—	No

​

Permission declaration

Each binary can publish its permission declaration to Access Manager at startup. These variables are separate from AUTH_ENABLED.

Variable	Description	Default	Required
IDP_DECLARATION_ENABLED	Set true to publish the permission declaration at startup. Set true or false.	false	No
IDP_HOST	Absolute http or https URL of the Access Manager Identity service.	—	If the declaration is on
IDP_M2M_CLIENT_ID	Client ID that the binary publishes with.	—	If the declaration is on
IDP_M2M_CLIENT_SECRET	Client secret that the binary publishes with. Sensitive.	—	If the declaration is on
PLUGIN_AUTH_ENABLED	Turns on the token request that the publication needs. It must be true when the declaration is on. Set true or false.	false	If the declaration is on

With IDP_DECLARATION_ENABLED=true, the binary does not start when one of the three required variables is empty, when IDP_HOST is not valid, or when PLUGIN_AUTH_ENABLED is not true. The publication also needs the Access Manager address, set as PLUGIN_AUTH_ADDRESS. When Access Manager refuses the publication or does not answer, the binary still starts.

​

License

Every binary (spi, dict, brcode, and core) needs a license to start. One license covers all four binaries, and it is global: the rail reads no organization list.

Variable	Description	Default	Required
LICENSE_KEY	License key. The rail validates it at the Lerian license service, license.lerian.io, in every environment.	—	Yes
LICENSE_FILE_PATH	Path of a license file. When it is set, the rail uses the file and ignores LICENSE_KEY, and a file that the rail refuses stops the startup. Leave it empty and set LICENSE_KEY.	—	No

A binary stops at startup when neither variable is set, whatever ENV_NAME says. The license guard covers every route except /health, /readyz, /version, /metrics, so it also covers the BR Code payload and key-set routes. When the license is refused, at startup or in a later background check, the binary stops. A pod with LICENSE_KEY needs outbound HTTPS to license.lerian.io.

​

BACEN callback (inbound from SPI)

Variable	Description	Default	Required
BACEN_CALLBACK_TRUSTED_PROXY_CIDRS	CIDRs trusted as the source of BACEN callbacks. Set together with the header secret.	—	With the header secret
BACEN_CALLBACK_MTLS_HEADER_SECRET	Shared secret proving the upstream terminated the callback mutual TLS. At least 32 characters. Sensitive.	—	If an ICOM consumer is enabled

Outside a local environment, the rail needs exactly one callback mutual-TLS mode. In direct mode, set SERVER_TLS_CERT_FILE, SERVER_TLS_KEY_FILE, and SERVER_TLS_CLIENT_CA_FILE. In proxy mode, set TLS_TERMINATED_UPSTREAM=true, the trusted CIDRs, and the header secret.

​

SPI settlement transport (BACEN_SPI_*)

Connection to BACEN’s SPI settlement endpoint over the RSFN, with the secondary messaging channel and the file-transfer (ARQ) endpoint.

Variable	Description	Default	Required
BACEN_SPI_ENDPOINT	Primary SPI endpoint URL.	http://localhost:9900	Outside a local environment
BACEN_SPI_SECONDARY_ENDPOINT	Secondary messaging channel URL. The rail sends pain.013, pain.014, camt.025, and trck.002 on this channel. When it is unset, those sends fail.	—	If the secondary ICOM consumer is enabled
BACEN_ARQ_ENDPOINT	BACEN file-transfer endpoint URL. The rail fetches large statement files from it. The spi binary also downloads BACEN’s QR certificate list from it.	—	In the spi binary, with the payer-side resolve on and the test trust off, unless BACEN_ARQ_ENABLED is false
BACEN_ARQ_ENABLED	false turns off the file-transfer client, both the statement file fetch and the QR certificate list download, even with BACEN_ARQ_ENDPOINT set. Any other value leaves it to the endpoint. With false, the spi binary never refreshes the list, and brcode keeps the last stored list.	—	No
BACEN_SPI_PARTICIPANT_ISPB	The participant’s 8-character ISPB (digits or uppercase letters) for the SPI surface.	—	When live or if an ICOM consumer is enabled
BACEN_SPI_ALLOWED_ENDPOINT_HOSTS	Allow-list of hosts the SPI client may reach (SSRF guard). It must include the endpoint host.	—	Outside a local environment
BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS	Allow-list for the secondary endpoint.	—	No
BACEN_SPI_TIMEOUT_SEC	Request timeout (seconds).	30	No
BACEN_SPI_INITIATION_TIMEOUT_MS	Payment-initiation timeout (milliseconds).	150	No
BACEN_SPI_RETRY_ATTEMPTS	Maximum attempts per transport request, including the first one.	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. Must be true outside a local environment.	false	Outside a local environment
BACEN_SPI_OUTBOUND_QUOTA_LIMIT	Sustained outbound quota (requests per second). Must be positive.	—	If quota enabled
BACEN_SPI_OUTBOUND_QUOTA_BURST	Burst allowance above the quota. Must be positive.	—	If quota enabled
BACEN_SPI_CATALOGUE_VERSION	BACEN SPI message-catalogue version.	5.13.2	No
BACEN_SPI_XSD_DIR	Directory of the BACEN XSD schemas that validate the messages. A value you set is used as written, so it must hold the schemas of BACEN_SPI_CATALOGUE_VERSION.	The bundle of the catalogue version	No
BACEN_SPI_CATALOGUE_ROOT	Override root for the message catalogue.	—	No
BACEN_SPI_INTERNAL_CALLBACK_SECRET	Shared secret for the internal callback path. At least 32 characters when set. Sensitive.	—	In a protected environment or if an ICOM consumer is enabled

​

mutual TLS to BACEN

The BACEN_TLS_* files back the mutual-TLS channel to BACEN. The SPI and DICT clients share them.

Variable	Description	Default	Required
BACEN_TLS_CERT_FILE	Client certificate presented to BACEN.	—	When live
BACEN_TLS_KEY_KIND	Where the client private key is held: file or kmip.	file	No
BACEN_TLS_KEY_FILE	Client private key. Sensitive. It must be empty when the key kind is kmip.	—	When live and the key kind is file
BACEN_TLS_KMIP_PRIVATE_KEY_UID	UID of the client private key in the HSM.	—	If kmip
BACEN_TLS_KMIP_PUBLIC_KEY_UID	UID of the client public key in the HSM.	—	If kmip
BACEN_TLS_CA_FILE	CA bundle used to verify BACEN’s server certificate.	—	When live

With BACEN_TLS_KEY_KIND=kmip, the client private key stays in your HSM. The binary opens it through the KMIP connection of its own signer: set BACEN_SPI_SIGNER_KIND=kmip on spi or BACEN_DICT_SIGNER_KIND=kmip on dict. Startup is refused unless both UIDs are set and the private key UID differs from the UID of the signing private key. If the binary cannot open the key in the HSM, it does not become ready. A renewed BACEN_TLS_CERT_FILE must hold the certificate of the same HSM key: the binary refuses a certificate for another key and keeps the loaded certificate.

​

Message signing and certificates

Lerian SPI digitally signs its outbound messages. Pick a custody backend with BACEN_SPI_SIGNER_KIND.

With the kmip backend, a wrong signing private key UID or a wrong DigestInfo setting stops startup. The same holds for the KMIP backends of DICT and BR Code JOSE.

Variable	Description	Default	Required
BACEN_SPI_SIGNER_KIND	Signing custody backend: file, pkcs11, or kmip. A protected environment refuses file.	file	In a protected environment
BACEN_SPI_SIGNER_COMMON_NAME	Expected common name of the signing certificate.	—	Outside a local environment
BACEN_SPI_SIGNING_CERT_FILE	Path to the certificate bound to the signing key.	—	When live, or if pkcs11 or kmip
BACEN_SPI_SIGNING_KEY_FILE	Path to the signing private key (file backend). Sensitive.	—	When live with file
BACEN_SPI_VERIFY_CERT_FILE	Certificate bundle used to verify BACEN’s signature on inbound messages.	—	When live
BACEN_SPI_INBOUND_SIGNER_COMMON_NAME	Expected common name of the signer on inbound messages.	—	Outside a local environment
CERT_READINESS_MIN_DAYS	Minimum days to expiry of a certificate. A valid certificate with fewer days left keeps its readiness check up and logs a warning. An expired certificate reports its check down, and /readyz stays ready.	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. With DEPLOYMENT_MODE=saas, it must use https.	—	If kmip
BACEN_SPI_KMIP_CA_FILE	PEM bundle of the HSM’s private CA. The rail trusts it in addition to the system roots.	—	No
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: soft_fail, hard_fail, or disabled. A protected environment refuses disabled.	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

These variables control how the service stores and references large SPI payloads.

Variable	Description	Default	Required
BACEN_SPI_PAYLOAD_RESOLVER_KIND	Payload storage backend: in_memory or postgres. A protected environment refuses in_memory.	in_memory	In a protected environment
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-256 key for encrypting stored payloads. Sensitive.	—	If kind is postgres

​

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.	—	If the primary ICOM consumer is enabled
BACEN_ICOM_ISPB	Participant ISPB for the inbound channel. It must equal BACEN_SPI_PARTICIPANT_ISPB.	—	If an ICOM consumer is enabled
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

Either consumer requires a configured persistence backend, BACEN_ICOM_ISPB, BACEN_SPI_INTERNAL_CALLBACK_SECRET, and BACEN_CALLBACK_MTLS_HEADER_SECRET. The primary consumer also requires BACEN_ICOM_BASE_URL. The secondary consumer also requires BACEN_SPI_SECONDARY_ENDPOINT.

An enabled consumer requires the proxy callback mode: TLS_TERMINATED_UPSTREAM=true, no SERVER_TLS_CLIENT_CA_FILE, and BACEN_CALLBACK_TRUSTED_PROXY_CIDRS with the address the consumer forwards from. With the default SERVER_ADDRESS, that address is 127.0.0.1.

​

DICT client (BACEN_DICT_*)

Client for BACEN’s Pix key directory (DICT), including the NP endpoint for batch key-existence checks. The client does not read HTTP_PROXY or HTTPS_PROXY.

Variable	Description	Default	Required
BACEN_DICT_ENDPOINT	DICT endpoint URL.	http://localhost:9900	Outside a local environment
BACEN_DICT_PARTICIPANT_ISPB	Participant ISPB for the DICT surface.	—	Outside a local environment
BACEN_DICT_ALLOWED_ENDPOINT_HOSTS	Allow-list of hosts the DICT client may reach. It must include the endpoint host.	—	Outside a local environment
BACEN_DICT_TIMEOUT_SEC	DICT request timeout (seconds).	10	No
BACEN_DICT_CID_SET_FILE_MAX_BYTES	Largest CID set file, in bytes, that the rail downloads. The rail refuses a file that declares a larger size.	8589934592	No
BACEN_DICT_CID_SET_FILE_IDLE_TIMEOUT_SEC	Timeout for each read of a CID set file download (seconds).	60	No
BACEN_DICT_NP_ENDPOINT	NP endpoint URL for batch key-existence checks. When it is unset, the batch check answers 501. With DEPLOYMENT_MODE=saas, it must use https.	—	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. Any other value stops startup. A protected environment refuses file on the dict binary.	file	In a protected environment
BACEN_DICT_SIGNING_CERT_FILE	Path to the DICT signing certificate.	—	For the selected DICT custody path
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.	—	When live
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. With DEPLOYMENT_MODE=saas, it must use https.	—	If kmip
BACEN_DICT_KMIP_CA_FILE	PEM bundle of the HSM’s private CA. The rail trusts it in addition to the system roots.	—	No
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_OUTBOUND_QUOTA_ENABLED	Enable the client-side DICT request quota. false starts only in a local environment.	true	No
BACEN_DICT_ENTRIES_READ_CATEGORY	The participant’s DICT entry-read category, a letter from A to H.	—	For the dict binary while the quota is enabled
BACEN_DICT_SPONSORED_ENTRIES_READ_CATEGORIES	Entry-read categories of sponsored participants, as ispb:letter pairs. A participant without a pair uses H.	—	No
BACEN_DICT_QUERY_MONITOR_ENABLED	Enable the DICT query monitor. false starts only in a local environment. Its thresholds have defaults.	true	No

​

BR Code JOSE signing (BACEN_BRCODE_JOSE_*)

Signs dynamic BR Code payloads (JWS). When BACEN_BRCODE_JOSE_SIGNER_KIND is unset, JOSE is disabled and the public payload endpoints refuse to serve. With JOSE enabled, route the payload paths (/api/v1/brcode/payload/*) and the key-set path (/api/v1/brcode/.well-known/jwks.json) under PUBLIC_BASE_URL to the brcode binary, with no authorizer in front of them. The payer’s PSP calls these routes without a credential.

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.	—	If BR Code JOSE is enabled
BACEN_BRCODE_JOSE_SIGNING_KEY_FILE	Path to the JOSE signing private key (file backend). Sensitive.	—	If BR Code JOSE is enabled with file
BACEN_BRCODE_JOSE_KID	JWS key identifier (kid) header value.	—	If BR Code JOSE is enabled
BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH	PKCS#11 module path.	—	If BR Code JOSE is enabled with pkcs11
BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL	PKCS#11 token label.	—	If BR Code JOSE is enabled with pkcs11
BACEN_BRCODE_JOSE_PKCS11_PIN_FILE	Path to the token PIN file. Sensitive.	—	If BR Code JOSE is enabled with pkcs11
BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL	Signing-key label on the token.	—	If BR Code JOSE is enabled with pkcs11
BACEN_BRCODE_JOSE_KMIP_BASE_URL	KMIP service base URL. With DEPLOYMENT_MODE=saas, it must use https.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_CA_FILE	PEM bundle of the HSM’s private CA. The rail trusts it in addition to the system roots.	—	No
BACEN_BRCODE_JOSE_KMIP_VHSM	Virtual HSM identifier.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER	KMIP crypto user.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN	KMIP crypto-user token. Sensitive.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID	UID of the signing private key.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID	UID of the signing public key.	—	If BR Code JOSE is enabled with kmip
BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX	Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.	false	No

​

BR Code QR resolve (BACEN_BRCODE_QR_PAYER_*)

Controls the payer-side resolve of a dynamic QR. When the resolve is off, its operation answers 503.

Variable	Description	Default	Required
BACEN_BRCODE_QR_PAYER_ENABLED	Enable the payer-side resolve of dynamic QR codes.	false	No
BACEN_BRCODE_QR_PAYER_CERT_LIST_FILE	Test trust only: path to the zip that holds the certificate list with the simulated QR site’s certificate. A blank or unreadable file stops startup. Outside the test trust, brcode reads the list from the database and ignores this variable.	—	If the test trust is on
BACEN_BRCODE_QR_PAYER_TEST_TRUST	Development only: relaxes the QR site checks (extra root CAs from BACEN_BRCODE_QR_PAYER_TEST_TRUST_ROOT_CA_FILE, a site on a private network, no EV policy, revocation soft-fail). Startup stops unless ENV_NAME is development, develop, dev, local, or test, and with DEPLOYMENT_MODE=saas.	false	No
BACEN_BRCODE_QR_PAYER_TEST_TRUST_ROOT_CA_FILE	PEM file of the root CAs for the test trust.	—	If the test trust is on

With BACEN_ARQ_ENDPOINT set and BACEN_ARQ_ENABLED not false, the spi binary checks the certificate list every hour. When the stored list is 24 hours old, it downloads BACEN’s list over the BACEN_TLS_* files, validates it, and stores it in the database. A failed or invalid download keeps the last list. The ENV_NAME of the spi binary selects the list: production downloads the production list, and any other value downloads the homologação list. The brcode binary reads the stored list every minute and needs neither the BACEN_TLS_* files nor BACEN_ARQ_ENDPOINT for it, so brcode and spi must use the same PostgreSQL database. Until the first list is stored, the resolve answers 503. The spi binary stops at startup when BACEN_BRCODE_QR_PAYER_ENABLED is true in its own environment, the test trust is off, BACEN_ARQ_ENDPOINT is blank, and BACEN_ARQ_ENABLED is not false.

​

PII encryption and hashing

Every variable below holds sensitive key or pepper material. It protects personal data at rest through encryption and blind indexing. Never commit or log a value. Inject it at deploy time through your secret manager. A pepper or key rotation requires a planned re-index or re-encryption.

Each key is 32 bytes, raw or base64. Each pepper has at least 32 characters.

Variable	Description	Default	Required
DICT_KEY_PII_ENCRYPTION_KEY	AES key for DICT key-holder PII. Sensitive.	—	dict binary in a protected environment
DICT_KEY_BLIND_INDEX_PEPPER	Pepper for blind-indexing DICT key PII. Sensitive.	—	dict binary in a protected environment
DICT_AUDIT_HASH_PEPPER	Pepper for DICT audit-record hashing. Sensitive.	—	In a protected environment, or for the dict binary outside a local environment
AUDIT_HASH_PEPPER	Fallback audit-hash pepper, read only when DICT_AUDIT_HASH_PEPPER is unset. Sensitive.	—	No
SPI_RESPONSIBLES_ENCRYPTION_KEY	AES key for responsible-party PII. Sensitive.	—	spi binary in a protected environment
SPI_OPERATIONS_PII_ENCRYPTION_KEY	AES-256 key for operation PII. Sensitive.	—	Yes, for the spi binary
SPI_OPERATIONS_BLIND_INDEX_PEPPER	Pepper for blind-indexing operation PII. Sensitive.	—	Yes, for the spi binary
BRCODE_PII_ENCRYPTION_KEY	AES key for BR Code PII. Sensitive.	—	brcode binary in a protected environment
BRCODE_PII_BLIND_INDEX_PEPPER	Pepper for blind-indexing BR Code PII. Sensitive.	—	brcode binary in a protected environment

​

PostgreSQL

Variable	Description	Default	Required
POSTGRES_HOST	Primary PostgreSQL host.	localhost	Yes
POSTGRES_PORT	Primary PostgreSQL port.	5432	No
POSTGRES_USER	Database user.	brspi	No
POSTGRES_PASSWORD	Database password. Sensitive. Use an explicit secret in a protected environment.	In-code development password	No
POSTGRES_DB	Database name.	brspi	No
POSTGRES_SSLMODE	libpq TLS mode. A protected environment refuses disable. Use verify-full with a trusted CA for remote connections. require encrypts the channel but does not verify the server identity.	disable	In a protected environment
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. The service uses the replica only when its host and port are both set.	—	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. When unset, the replica uses the primary’s 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.	—	If REDIS_TLS=true
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

​

Regulatory archive (REGULATORY_ARCHIVE_*)

The spi and dict binaries keep the regulatory archive in S3-compatible storage. The brcode and core binaries do not use these variables.

Variable	Description	Default	Required
REGULATORY_ARCHIVE_BUCKET	Bucket that holds the archive.	—	Outside a development environment
REGULATORY_ARCHIVE_ENDPOINT	S3 API base URL. When it is unset, the rail uses the AWS regional endpoint. With DEPLOYMENT_MODE=saas, it must use https.	—	No
REGULATORY_ARCHIVE_REGION	Storage region.	—	If the bucket is set
REGULATORY_ARCHIVE_ACCESS_KEY	Access key. Set it together with the secret key. Without both, the rail uses the default AWS credential sources.	—	No
REGULATORY_ARCHIVE_SECRET_KEY	Secret key. Sensitive.	—	No
REGULATORY_ARCHIVE_USE_PATH_STYLE	Use path-style bucket addressing.	false	No
REGULATORY_ARCHIVE_SSE_ALGORITHM	Server-side encryption: AES256, aws:kms, or none. none starts only in a development environment.	—	If the bucket is set
REGULATORY_ARCHIVE_SSE_KMS_KEY_ID	KMS key ID for aws:kms encryption.	—	If the encryption is aws:kms
REGULATORY_ARCHIVE_OBJECT_LOCK_MODE	Object Lock mode: COMPLIANCE, GOVERNANCE, or none. none starts only in a development environment.	—	If the bucket is set

Here, a development environment means that ENV_NAME is development, develop, dev, local, or test, and DEPLOYMENT_MODE is not saas. These rules read ENV_NAME as set, so an unset ENV_NAME is not a development environment. A missing required variable stops startup. In a development environment without a bucket, the rail archives nothing. With the archive on, /readyz on spi and dict reports the archive check down while the bucket does not answer, and stays ready.

​

Outbox and streaming

Lerian SPI publishes events through a transactional outbox and a streaming producer, and consumes settlement events for BR Code. The BR Code settlement consumer runs unconditionally. Streaming has no enable switch: STREAMING_BROKERS is required at startup, including when OUTBOX_ENABLED=false. Each binary requires its own fixed STREAMING_CLOUDEVENTS_SOURCE value, and any other value stops startup: br-spi for spi, br-spi-dict for dict, br-spi-brcode for brcode, and br-spi-core for core.

A STREAMING_EVENT_POLICIES entry that switches off a Lerian SPI event stops startup. Only the two spi_tracking events and three dict_med_operations events (inconsistent_projection, feed_blocked, and feed_record_abandoned) can be switched off.

Variable	Description	Default	Required
OUTBOX_ENABLED	Enable the transactional outbox dispatcher. Must be true for the spi, dict, and brcode binaries in a protected environment.	true	No
OUTBOX_DISPATCH_INTERVAL_MS	Interval between dispatch cycles (milliseconds).	100	No
OUTBOX_BATCH_SIZE	Rows drained per dispatch cycle.	50	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
SPI_PARTICIPANT_CONSUMER_ENABLED	Enable the Core-to-SPI participant-request consumer. It subscribes to the Core producer’s application stream; the topic is derived and not configurable. It requires STREAMING_BROKERS, BACEN transport, and persistence when enabled.	false	No
CORE_PARTICIPANT_CONSUMER_ENABLED	Enable the Core consumer that applies participant confirmations from the SPI binary. Set true or false. Any other value stops startup.	false	No
CORE_SETTLEMENT_COMPLETION_CONSUMER_ENABLED	Enable the Core consumer that moves a settlement from PENDING to SETTLED. Set true or false. Any other value stops startup.	false	No
CORE_SETTLEMENT_TERMINATION_CONSUMER_ENABLED	Enable the Core consumer that applies returns and failures to settlements. Set true or false. Any other value stops startup.	false	No

​

Schedulers

Background jobs, each with its own switch. The two DICT jobs that default to true carry regulatory duties, so the dict binary starts its scheduler for them unless SCHEDULER_ENABLED=false. The spi binary does the same for the schedule verdict and portability deadline jobs. The jobs that default to false also need SCHEDULER_ENABLED=true. DICT discovery and inventory workers have their own controls in the next section.

Variable	Description	Default	Required
SCHEDULER_ENABLED	Master switch for the scheduler subsystem. An explicit false stops every job below.	false	No
SCHEDULER_CLAIM_DEADLINE_ENABLED	Run the DICT claim-deadline job.	true	No
SCHEDULER_INBOUND_DISCOVERY_ENABLED	Run the DICT claim discovery walks, for the donor and the claimer sides.	true	No
SCHEDULER_INBOUND_DISCOVERY_INTERVAL	Interval between ticks of the claim discovery walks. Must be greater than zero and at most one minute.	15s	No
SCHEDULER_INBOUND_DISCOVERY_MAX_STALENESS_MINUTES	Readiness staleness threshold for the claim discovery walks. Must be greater than zero.	15	No
SCHEDULER_QUOTA_RESET_ENABLED	Run the daily participant-quota reset in Core, at midnight Brasília time.	false	No
SCHEDULER_DICT_AUDIT_RETENTION_ENABLED	Run the DICT audit-log retention purge.	false	No
SCHEDULER_APPROVAL_EXPIRY_ENABLED	Every 5 minutes, move expired approval requests to EXPIRED.	false	No
SCHEDULER_PORTABILITY_DEADLINE_ENABLED	Every 5 minutes, mark portability operations whose 24-hour deadline has passed. It also hands back to the operator a portability operation whose reda.031 has waited 30 minutes for BACEN’s answer. It never confirms them.	true	No
SCHEDULER_SCHEDULE_VERDICT_RECONCILER_ENABLED	Every 5 minutes, publish the missing verdict event of a Pix Automático schedule operation that closed 15 minutes to 24 hours earlier. It does not run when OUTBOX_ENABLED=false.	true	No

​

DICT discovery and inventory

The workers below run independently of SCHEDULER_ENABLED, each with its own switch.

Variable	Description	Default	Required
DICT_FUNDS_RECOVERY_EVENTS_ENABLED	Enable the DICT funds-recovery event feed.	true	No
DICT_FUNDS_RECOVERY_EVENTS_MAX_STALENESS_MINUTES	Readiness staleness threshold for the funds-recovery event feed.	15	No
DICT_FUNDS_RECOVERY_EVENTS_GAP_BLOCK_HOURS	Gap threshold after which the funds-recovery event feed records a blocked marker. Must be greater than zero.	168	No
DICT_INFRACTION_DISCOVERY_ENABLED	Enable the DICT infraction discovery walk.	true	No
DICT_INFRACTION_DISCOVERY_MAX_STALENESS_MINUTES	Readiness staleness threshold for infraction discovery. Must be greater than zero.	15	No
DICT_REFUND_DISCOVERY_ENABLED	Enable the DICT refund discovery walks.	true	No
DICT_REFUND_DISCOVERY_MAX_STALENESS_MINUTES	Readiness staleness threshold for refund discovery. Must be greater than zero.	15	No
DICT_PERSON_WATCHLIST_ENABLED	Enable polling for documents in the DICT person watchlist.	true	No
DICT_PERSON_WATCHLIST_CADENCE_MINUTES	Minimum age before a watched document is observed again. Must be greater than zero.	60	No
DICT_PERSON_WATCHLIST_BATCH_LIMIT	Maximum watched documents observed in one polling tick. Must be greater than zero.	100	No
DICT_PERSON_WATCHLIST_MAX_DOCUMENTS_PER_PARTICIPANT	Maximum active watched documents per participant. Must be greater than zero.	500	No
DICT_PERSON_WATCHLIST_MAX_OBSERVATION_AGE_MINUTES	Readiness threshold for the oldest watched document observation. Must be greater than zero.	360	No
DICT_PERSON_WATCHLIST_QUARANTINE_AFTER_FAILURES	Consecutive failed observations before a watched document is quarantined. Must be greater than zero.	6	No
DICT_FRAUD_MARKER_INVENTORY_ENABLED	Enable the DICT fraud-marker inventory sweep.	true	No
DICT_FRAUD_MARKER_INVENTORY_SWEEP_MINUTES	Interval between fraud-marker inventory sweeps. Must be greater than zero.	60	No
DICT_FRAUD_MARKER_INVENTORY_MAX_DOCUMENTS_PER_SWEEP	Maximum documents reconciled in one inventory sweep. Must be greater than zero.	200	No
DICT_FRAUD_MARKER_INVENTORY_MAX_STALENESS_MINUTES	Readiness staleness threshold for the fraud-marker inventory. Must be greater than zero.	180	No

​

Rate limiting, idempotency, and connectivity

Variable	Description	Default	Required
RATE_LIMIT_ENABLED	Enable request rate limiting. Forced on in a protected environment.	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
IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY	AES-256 key for encrypting stored idempotency responses. Sensitive.	—	Yes
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.	true	No

See Systemplane 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_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 a protected environment.	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 for the probe contract.

The /readyz response includes a license check. With LICENSE_KEY, the check is always up and makes no call to the license service, so an invalid license does not turn /readyz to 503. A license that the rail refuses stops the binary, at startup or in a later background check.

The certificate checks, the signer-custody check, and the regulatory-archive check report their real status in the /readyz body. When one reports down, /readyz stays ready.