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

# Plugin SISBAJUD environment variables

> Environment variables of Plugin SISBAJUD: runtime, authentication, license, key management, the Mensageria connection, execution timing, the webhook listener, Midaz, and event streaming.

This page lists the environment variables of **Plugin SISBAJUD**. [Lerian SISBAJUD Mensageria environment variables](https://docs.lerian.studio/en/rails/sisbajud/sisbajud-environment-variables.md) lists the variables of the Mensageria. [BYOC configuration essentials](https://docs.lerian.studio/en/reference/byoc-configuration.md) documents the variables that every Lerian Go service shares: server, datastores, telemetry, and plugin authentication.

In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required**) marks the variables you must set. `—` means no default. A variable marked **Sensitive** holds a credential or key material. Inject it from your secret manager at deploy time. Do not commit its value.

`EXECUTOR_ENABLED=true` turns on the plugin. With `EXECUTOR_ENABLED` blank, a non-blank `MENSAGERIA_BASE_URL` also turns it on, and `false` does not turn off the plugin of a configured Mensageria. With `EXECUTOR_ENABLED=true` and no `MENSAGERIA_BASE_URL`, the plugin runs without the Mensageria, for the direct channel only. Then it needs `EXECUTOR_M2M_SUBJECT`, `RESPONSE_DEADLINE_MARGIN`, and `EXECUTOR_HEARTBEAT_EVERY`. It does not read the Mensageria client, mTLS, or webhook listener variables, except `EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS`, which caps the attempts on each direct order.

To install or upgrade the plugin, see the [chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-br-sisbajud).

## Service and runtime

| Variable | Default / Required | Description |
| - | - | - |
| `SERVER_ADDRESS` | **Set it to `:4029`** | Listen address of the main API. The image exposes port 4029. `/health`, `/readyz`, and `/version` use this port. |
| `ENVIRONMENT_NAME` | — | Runtime environment. `local`, `development`, `staging`, `e2e`, and `test` are non-production values. Any other value, and no value, runs the production checks. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc`, or `saas`. With `saas`, the boot refuses a PostgreSQL or Redis connection without TLS. Outside `local`, the webhook listener needs TLS. |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | Tenant of a single-tenant deployment. It must be a UUID. |
| `EXECUTOR_ENABLED` | — | `true` or `false`. Any other value refuses the boot. |
| `SYSTEMPLANE_ENABLED` | `false` | Serve the [Systemplane](https://docs.lerian.studio/en/reference/platform/systemplane/overview.md) admin API under `/system`, and the accounting-route documents under `/tenant-system`. |

> [!NOTE]
>
> The production checks require `POSTGRES_PASSWORD` and refuse `POSTGRES_SSLMODE=disable`. With `STREAMING_ENABLED=true`, they also require `STREAMING_TLS_ENABLED=true`.

## Authentication

| Variable | Default / Required | Description |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `false` | Check bearer tokens on the main API with the Access Manager. With `false`, the plugin does not serve the credential key rotation, the human-decision resolution, the result re-arm, the parked-attempt resolution, the direct-order erase, or the purge preview, and the direct channel answers `501`. |
| `PLUGIN_AUTH_HOST` | **Required** | Address of the Access Manager. The plugin gets its token for the Mensageria from this address, also when `PLUGIN_AUTH_ENABLED` is `false`. |

## License

[License Manager](https://docs.lerian.studio/en/platform/licensing/license-manager.md) describes how the product checks the license.

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | **Required** | The license key that Lerian issued for Plugin SISBAJUD. The boot refuses an empty value in every environment. The license is global, so no other variable sets its scope. |

## Key management

| Variable | Default / Required | Description |
| - | - | - |
| `KMS_PROVIDER` | **Required when `ENVIRONMENT_NAME` is `production`** | Key manager: `vault` (HashiCorp Vault Transit) or `aws` (AWS KMS). Any other value refuses the boot. With any other environment, an unset value means `vault`. |
| `AWS_REGION` | **Required with `aws`** | Region of AWS KMS. |
| `KMS_AWS_KEY_MODE` | **Required with `aws`** | `managed` or `provided`. It has no default. Any other value refuses the boot. |
| `KMS_AWS_KEY_ARN` | **Required with `provided`** | ARN of your AWS KMS key for the institution data, in the region of `AWS_REGION`. An alias ARN refuses the boot. With `managed`, leave it empty. |
| `KMS_AWS_CREDENTIALS_KEY_ARN` | **Required with `provided`** | ARN of your AWS KMS key for the stored connector credentials, with the same rules. It must be a different key from `KMS_AWS_KEY_ARN`. |
| `KMS_AWS_ROTATION_CHECK_INTERVAL_SEC` | `3600` | With `provided`, the interval, in seconds, at which the plugin looks for a rotation of your keys. From `1` to `86400`. |
| `KMS_AWS_TIMEOUT_SEC` | `20` | Timeout of each AWS KMS call, in seconds. From `1` to `600`. |
| `VAULT_ADDR` | **Required with `vault`** | Address of your Vault. |
| `VAULT_AUTH_METHOD` | `token` | `token` or `approle`. Any other value refuses the boot. |
| `VAULT_TOKEN` | **Required for `token` when `ENVIRONMENT_NAME` is `production`** | Vault token. Sensitive. |
| `VAULT_APPROLE_ROLE_ID` | **Required for `approle`** | AppRole role ID. Sensitive. |
| `VAULT_APPROLE_SECRET_ID` | **Required for `approle`** | AppRole secret ID. Sensitive. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Mount path of the Transit engine. |
| `VAULT_TIMEOUT_SEC` | `15` | Timeout of each Vault request, in seconds. From `1` to `600`. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Renew the Vault token in the background. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Minimum time between two renewals, in seconds. |

With AWS KMS, the two key modes are:

* **`managed`.** The plugin creates two keys for each institution: one for its data and one for its stored connector credentials. `credential-kek:rotate` rotates the credentials key.
* **`provided`.** You create the two keys. The plugin never creates or rotates them, and `credential-kek:rotate` returns `422`. When your key custodian rotates a key, the plugin records the new version.

The key requirements, the AWS credentials, the permissions except `kms:ListAliases`, and the encryption context are the same as on the Mensageria. [AWS KMS on the Mensageria](https://docs.lerian.studio/en/rails/sisbajud/sisbajud-environment-variables.md#aws-kms) lists them. Choose the key provider once. When the database holds data that another key provider protects, the boot refuses.

## Mensageria connection

The plugin calls the execution API of the Mensageria. [Integrating with Lerian SISBAJUD](https://docs.lerian.studio/en/rails/sisbajud/sisbajud-integration.md#execution-api) describes it.

| Variable | Default / Required | Description |
| - | - | - |
| `MENSAGERIA_BASE_URL` | **Required** with the Mensageria | Base URL of the execution API of the Mensageria (`SISBAJUD_EXECUTION_ADDRESS` on the Mensageria). It must be an `https` URL with a host. |
| `MENSAGERIA_MTLS_ENABLED` | `false` | `true` presents a client certificate. `false` uses one-way TLS. Any other value refuses the boot. |
| `MENSAGERIA_TLS_CA_FILE` | **Required if `MENSAGERIA_MTLS_ENABLED=true`** | CA bundle that verifies the Mensageria. With one-way TLS, it is optional, and an empty value uses the system trust store. |
| `MENSAGERIA_TLS_CLIENT_CERT_FILE` | **Required if `MENSAGERIA_MTLS_ENABLED=true`** | Client certificate of the plugin. |
| `MENSAGERIA_TLS_CLIENT_KEY_FILE` | **Required if `MENSAGERIA_MTLS_ENABLED=true`** | Private key of that certificate. Sensitive. |
| `EXECUTOR_M2M_SUBJECT` | **Required** | The `sub` of the M2M token of the plugin. The plugin records it as the owner of each institution that it creates. |
| `MENSAGERIA_CLIENT_ID` | **Required** | Client ID of the M2M client of the plugin. |
| `MENSAGERIA_CLIENT_SECRET` | **Required** | Client secret of that client. Sensitive. The boot refuses a pair with only one of the two values. |
| `STREAMING_HUB_TENANT_ID` | **Required** | Tenant of the canary probes. |

## Execution timing

| Variable | Default / Required | Description |
| - | - | - |
| `EXECUTOR_TICK_EVERY` | `30s` | Interval of the execution cycle. Go duration greater than 0. |
| `EXECUTOR_HEARTBEAT_EVERY` | **Required** | Interval of the heartbeats for a write whose outcome is not known. Go duration greater than 0. |
| `EXECUTOR_HUMAN_DECISION_AFTER_BEATS` | `3` | Number of heartbeats without a change before the order goes to a human decision. |
| `EXECUTOR_RESULT_MAX_ATTEMPTS` | `12` | Number of failed posts of one result before the plugin parks it, records a human decision, and raises an alarm. `0` means the default. A negative value refuses the boot. A platform administrator re-arms a parked result. |
| `RESPONSE_DEADLINE_MARGIN` | **Required** | Go duration greater than 0, for example `2h`. Before the order deadline, the plugin keeps this margin and hands an unresolved write to a human decision. |
| `EXECUTOR_SETTLE_WINDOW` | `1s` | Go duration. Set it to at least the asynchronous latency of your ledger. |
| `EXECUTOR_ORPHAN_RECONCILE_WINDOW` | `48h` | How far back the plugin looks for operations on block accounts that it did not write. |

## Webhook listener

| Variable | Default / Required | Description |
| - | - | - |
| `EXECUTOR_TRANSPORT` | `webhook` | How the execution notices reach the plugin. This page describes `webhook`. |
| `EXECUTOR_HUB_WEBHOOK_ADDRESS` | `:9082` | Listen address of the webhook listener. |
| `EXECUTOR_HUB_WEBHOOK_PATH` | `/v1/webhooks/hub` | Route of the webhook listener. It must start with `/`. |
| `EXECUTOR_HUB_WEBHOOK_SECRET` | **Required** | Signing secret of the Streaming Hub subscription. Sensitive. |
| `EXECUTOR_HUB_WEBHOOK_SECRET_PREVIOUS` | — | The secret before the last rotation. The listener accepts both secrets. Sensitive. |
| `EXECUTOR_HUB_WEBHOOK_MAX_SKEW_SEC` | `300` | From `1` to `300`. The listener accepts a delivery outside this clock skew, with a warning in the log. |
| `EXECUTOR_HUB_WEBHOOK_TLS_CERT_FILE` | **Required outside `DEPLOYMENT_MODE=local`, unless TLS is terminated upstream** | Server certificate of the listener. Set it together with the key. |
| `EXECUTOR_HUB_WEBHOOK_TLS_KEY_FILE` | **Required with the certificate** | Private key of that certificate. Sensitive. |
| `EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED` | `false` | Set it to `true` when TLS is terminated in front of the listener. |
| `EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS` | `5` | Number of attempts for each accepted delivery. It must be at least 1 + `EXECUTOR_SETTLE_WINDOW` / `EXECUTOR_TICK_EVERY`, rounded up. |

## Direct channel

The direct channel needs `PLUGIN_AUTH_ENABLED` on, one tenant, and the executor mode. [How Plugin SISBAJUD runs orders](https://docs.lerian.studio/en/interfaces/plugin-sisbajud/plugin-sisbajud-how-it-works.md#direct-channel) describes it.

| Variable | Default / Required | Description |
| - | - | - |
| `DIRECT_PERMANENT_BLOCK_ENABLED` | `false` | `true` or `false`. Any other value refuses the boot. With `false`, the channel refuses a new permanent block with `SBJ-0027`. With `false`, the active permanent blocks keep blocking new credits until they close. With `true`, the plugin takes a new permanent block, and the boot needs `STREAMING_ENABLED` `true` and `STREAMING_BROKERS`. `STREAMING_BROKERS` must reach the brokers where Midaz publishes its ledger events: without them, the plugin captures no later credit. |
| `DIRECT_PERMANENT_REFRESH_EVERY` | `15m` | How often the plugin refreshes the accounts of the subject of a permanent block. From `1m` to `15m`. |
| `EXECUTOR_PERMANENT_RESULT_EMITTER_ENABLED` | `false` | `true` or `false`. With `true`, the plugin writes a result for each subsequent block of a permanent block. It needs `DIRECT_PERMANENT_BLOCK_ENABLED` `true`. The plugin holds a result and raises an alarm when `connectorMetadata.permanentProducts` does not map the account type. |
| `EXECUTOR_ORDER_SWEEP_ENABLED` | `false` | `true` or `false`. With `true`, the plugin closes the finished revisions of both channels. |
| `EXECUTOR_DIRECT_DRAINER_INFRA_ALARM_THRESHOLD` | `3` | The plugin raises an alarm when a direct order reaches each multiple of this number of consecutive infrastructure errors. At least `1`. |
| `EXECUTOR_DIRECT_PURGE_ELIGIBLE_ALARM_AFTER` | `168h` | Go duration above 0. The plugin logs an error when the oldest direct order that can be erased has waited this long, so that an administrator reviews it. An invalid value stops the plugin at startup. |
| `EXECUTOR_DIRECT_PURGE_REFRESH_EVERY` | `15m` | Go duration above 0. How often the plugin counts the direct orders that can be erased. An invalid value stops the plugin at startup. |

## Midaz

| Variable | Default / Required | Description |
| - | - | - |
| `MIDAZ_CRM_MODE` | `legacy` | CRM surface of the institutions that set no `crmMode`: `legacy` (the standalone Midaz CRM at `crmBaseUrl`) or `embedded` (the CRM of the Midaz ledger at `baseUrl`). |

The plugin reads the Midaz connection of each institution from its configuration, not from environment variables. [Operating Plugin SISBAJUD](https://docs.lerian.studio/en/interfaces/plugin-sisbajud/plugin-sisbajud-operations.md#institution-setup) describes it.

## Event streaming

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | `true` | Publish events. A credential key rotation publishes `kek.rotated`. The boot refuses `false` when `STREAMING_BROKERS` is set. |
| `STREAMING_BROKERS` | — | Comma-separated list of Kafka brokers. |
| `STREAMING_TLS_ENABLED` | **`true` in production** | Connect to the brokers over TLS. |
| `OUTBOX_ENABLED` | `true` | Durable delivery path of events. `STREAMING_ENABLED=true` requires it. |

## Values that must match the Mensageria

* **`RESPONSE_DEADLINE_MARGIN`.** The Mensageria reads the same variable. Set the same value on the Mensageria and on Plugin SISBAJUD.
* **Mutual TLS.** Set `MENSAGERIA_MTLS_ENABLED` to the same value as `SISBAJUD_EXECUTION_MTLS_ENABLED` on the Mensageria. With mutual TLS on the Mensageria and off on the plugin, the TLS handshake fails.
* **Plugin identity.** `EXECUTOR_M2M_SUBJECT` is the `sub` of the token of the M2M client in `MENSAGERIA_CLIENT_ID`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.