Health and readiness
GET /health reports liveness. GET /readyz runs every dependency probe and reports one status.
GET /readyz/tenant/{id} reports the same detail for one institution. READYZ_PROBE_TIMEOUT_SEC bounds each probe at 5 seconds. READYZ_DEP_SLOW_THRESHOLD_MS marks a slow dependency at 500 milliseconds.
An unreachable Reporter removes the instance from service. Start the Reporter first.
Runtime configuration
A small set of knobs changes without a restart. Set
SYSTEMPLANE_ENABLED=true to mount the runtime plane.
Each group is one namespace under this service’s configuration prefix.
Read a namespace with
GET /system/{namespace} and one key with GET /system/{namespace}/{key}. Write one key with PUT /system/{namespace}/{key}. Only a platform administrator may call these routes.
Everything else comes from the environment and needs a restart: connection strings, pools, TLS material, listeners, and the authentication gate. See Systemplane for the runtime-plane contract.
Credentials and keys
Set
PLUGIN_AUTH_ENABLED=true and PLUGIN_AUTH_HOST to gate the API. The same pair drives outbound authentication.
Each upstream carries its own credential. Lerian STA uses STA_CLIENT_ID and STA_CLIENT_SECRET. Lerian Reporter uses REPORTER_CLIENT_ID and REPORTER_CLIENT_SECRET. There is no shared credential and no fallback.
With the gate on, a missing pair stops the boot and names the exact variable. Lerian CCS mints each token through OAuth2 client credentials and caches it for M2M_CREDENTIAL_CACHE_TTL_SEC seconds, 300 by default. Multi-institution deployments read per-institution credentials from AWS Secrets Manager instead.
CCS_CRYPTO_MASTER_KEY holds the AES-256-GCM master key for data encrypted at rest. It takes 64 hexadecimal characters. An empty value stops the boot.
Lerian CCS can verify a signature on each inbound event from Lerian STA. Set STA_EVENT_HMAC_VERIFY_ENABLED=true, load the key catalogue into STA_EVENT_HMAC_MASTER_KEYS, and name the active version in STA_EVENT_HMAC_MASTER_KEY_VERSION. Load the catalogue first. STA_EVENT_HMAC_TOLERANCE_SECONDS bounds the clock skew at 300 seconds.
Storage, outbox and retention
Two object-storage buckets hold the regulatory XML:
OBJECT_STORAGE_STA_BUCKET inbound and OBJECT_STORAGE_CCS_BUCKET outbound. Only file references travel over the wire.
Outbound work leaves through a transactional outbox table. The dispatcher reads it every OUTBOX_DISPATCH_INTERVAL_SEC seconds, 2 by default, in batches of OUTBOX_BATCH_SIZE, 50 by default, and gives up on an event after OUTBOX_MAX_DISPATCH_ATTEMPTS attempts, 10 by default. Set CCS_OUTBOX_OVERRIDES_ENABLED=true to move the dispatcher onto the CCS_OUTBOX_* interval, batch size and attempt budget instead. A message that exhausts its attempt budget moves to the dead-letter queue under CCS_OUTBOX_DLQ_ROUTING_KEY, and that key applies in both cases.
CCS_OUTBOUND_RETENTION_DAYS and CCS_ACCS009_RETENTION_DAYS both default to 30 days. A monitor scans for a missing remittance every CCS_NON_SUBMISSION_SCAN_INTERVAL_SEC seconds, 3600 by default.
The service never applies its own database schema. A separate migration job applies it before startup.
Parked STA responses
An inbound file that Lerian CCS cannot apply parks in a dead-letter queue with its payload intact. A park retains an open pendency. The parked file is often the only copy of a BACEN fact, so it needs an alert and a human decision.
POST /v1/batches/{id}/drain-parked-response applies a late ACCS003 to a batch that already reached a terminal state. The caller supplies identifiers only. Lerian CCS re-fetches the file, re-derives the verdicts, and refuses when the named batch does not match. It writes an audit entry in the same transaction.
Do not drain when two batches match one file, or when the correlation contradicts itself. Establish which batch produced the file first. Treat the disagreement as the finding.
Metrics and tracing
GET /metrics serves the readiness metrics in Prometheus text format. Set ENABLE_TELEMETRY=true to export traces and metrics over OTLP to OTEL_EXPORTER_OTLP_ENDPOINT. See Observability for the platform view.
Deployment posture
DEPLOYMENT_MODE takes local, byoc, saas or onprem. In saas, the service enforces TLS on every dependency. CCS_RUN_MODE takes manager, worker or all, and selects which subsystems run.
Production adds these requirements.
PLUGIN_AUTH_ENABLED=truewithPLUGIN_AUTH_HOST.LICENSE_KEYandORGANIZATION_IDS.CIRCUIT_BREAKER_ENABLED=true, which the Reporter integration needs.REPORTER_URLandCCS_CRYPTO_MASTER_KEY, both always mandatory.