Settings
Four bootstrap values live outside the database (DB__PROVIDER, DB__CONNECTION, DB__MIGRATOR_CONNECTION, BOOKEND_MASTER_KEY), alongside a few optional container environment variables described in the Installation Guide (for example Licensing__PublicKeyPath). Everything else is a row in settings, edited through the setup wizard, the Settings screen, or PUT /v1/settings/{namespace} (administrators only). Secret values are AES-GCM encrypted with the master key and never returned by the API; saving a blank secret keeps the stored value. Changes apply within 30 seconds; the few settings flagged restart required take effect after the api restarts.
Where to find them
Section titled “Where to find them”Settings in the left navigation has five tabs:
| Tab | Who | What |
|---|---|---|
| Rules | everyone | Every check Bookend runs. Administrators switch rules off or on and add bank rules in one sentence. |
| Documents | administrators | The template studio: teaching documents Bookend does not recognize. |
| Approval record | administrators | LAR profiles: how Bookend reads your approval record. |
| Core boarding | administrators | Core field maps: where each value lands in your core. |
| Other options | administrators | Every remaining setting by namespace (“Show options for”), test buttons for smtp, core and inference, and Reopen the setup wizard…. |
Reopening the setup wizard keeps settings and data but returns the install to setup: until an administrator activates it again (step 10), every user is sent to the wizard and scheduled heartbeats pause.
Namespaces
Section titled “Namespaces”Defaults are in parentheses. Unknown keys, read-only keys and values of the wrong type are refused with field errors.
| Namespace | Keys | Notes |
|---|---|---|
app |
public_url |
the URL users type; sign-in links and emails are built from it |
auth |
access_token_minutes (15, max 60), refresh_token_hours (8, max 720), otp_ttl_minutes (15), password_min_length (12, 8 to 128), login_password_enabled (true), login_otp_enabled (true), login_totp_enabled (false), oidc_enabled, oidc_authority, oidc_client_id, oidc_client_secret (secret), oidc_provider_name, allowed_email_domains (JSON array, empty = any), otp_link_path (/auth/otp), signing_key (secret), signing_key_id |
sign-in policy, MFA and single sign-on; see Users and roles. The RS256 signing key and its id are generated on first boot and read-only |
smtp |
host, port (587), tls_mode (none / starttls / ssl; starttls), username, password (secret), from_address, from_name (Bookend) |
read on every send, no restart; the test button sends a real message to you and records the result |
documents |
max_package_mb (200), retention_days (2555), last_retention (read-only), watch_folder (/data/watch, restart required), watch_interval_seconds (60), watch_stable_seconds (5), page_render_dpi (110), taxonomy (JSON, read-only) |
the nightly retention sweep purges the stored bytes of loans sealed longer ago than retention_days; rows, hashes and evidence stay |
fields |
catalog (JSON, read-only) |
the canonical field catalog the rules and maps refer to |
extraction |
templates (JSON) |
the bank’s own document templates, taught in Settings → Documents; see Teaching documents |
ai |
endpoint, model, api_key (secret) |
optional OpenAI-compatible endpoint that can draft a template from a sample; never used at runtime |
execution |
templates (JSON) |
signature, initials, date and notary zones per document type |
inference |
url (http://inference:9090) |
the inference container; the test button calls its health check |
pipeline |
max_attempts (8), retry_base_seconds (5) |
exponential backoff for stage retries, capped at 10 minutes |
rules |
ruleset_version (v1.0, read-only), money_tolerance_cents (0), rate_tolerance (0.00001), date_tolerance_days (0), name_normalization (lenient / strict; lenient), disabled (JSON), custom (JSON), catalog (JSON, read-only) |
disabled and custom are managed on the Rules tab; see Reconciliation rules |
review |
reason_codes (JSON array), justification_min_length (10) |
override policy |
core |
provider (file.export / jackhenry.jxchange; file.export), file_export_path (/data/exports), jxchange.endpoint, jxchange.username, jxchange.password (secret), jxchange.institution_id |
the test button probes the active adapter |
boarding |
allow_wire_before_boarded (false) |
wires normally wait for a boarded loan |
metering |
heartbeat_enabled (true), air_gapped (false), endpoint, api_key (secret, optional) |
see Metering and licensing |
license |
key (secret); institution, tier, expires_at (read-only) |
the license JWT and the values read from it |
evidence |
last_verification (JSON, read-only) |
written by the nightly evidence sweep |
setup |
state, completed_steps, smtp_tested, core_tested, lar_profile_id, activated_at (all read-only) |
wizard bookkeeping; lar_profile_id is the approval-record profile used for intake |
Reference catalogs
Section titled “Reference catalogs”The document taxonomy, field catalog and rule catalog are JSON settings rather than code (ADR 0003). They ship with each release and are read-only through the API, and every reconciliation run records the ruleset version and thresholds it used. What a bank changes without a release: rule switches and bank rules (Rules tab), taught document templates (Documents tab), execution templates, tolerances, reason codes, retention and the integration settings.
Every settings write is a row in the data audit (GET /v1/audit?source=data&table=settings) with the actor and the before and after values. Secret values appear there only in encrypted form.
