Health and readiness
GET /health reports liveness. GET /readyz runs every dependency probe and reports one status.
GET /readyz/tenant/{id} reports postgres, redis and rabbitmq for one institution.
An unreachable Reporter removes the instance from service. Start the Reporter first.
Credentials and keys
PLUGIN_AUTH_ENABLED=true with PLUGIN_AUTH_HOST makes Access Manager authorize each API request. The same pair mints the outbound tokens.
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.
Lerian CCS mints a token through OAuth2 client credentials for each outbound call. Outside saas, with the gate on, a missing pair stops the boot and names the exact variable. In saas, Lerian manages each institution’s credential, and the rail caches the credential for M2M_CREDENTIAL_CACHE_TTL_SEC seconds, 300 by default.
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. The service refuses an event whose signature does not match.
Storage, outbox and retention
Two object-storage buckets hold the regulatory XML:
OBJECT_STORAGE_STA_BUCKET inbound and OBJECT_STORAGE_CCS_BUCKET outbound. The API and the broker messages carry file references only.
Outbound work leaves through a transactional outbox table, so the service needs OUTBOX_ENABLED=true to start. 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. When an ACCS001 hand-off exhausts its attempt budget, its batch moves to SUBMIT_FAILED.
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
When Lerian CCS cannot apply an inbound file, it parks the file event in a dead-letter queue. The file stays in the inbound bucket. It 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 or saas. CCS_RUN_MODE takes manager, worker or all, and selects which subsystems run.
Production adds these requirements.
PLUGIN_AUTH_ENABLED=truewithPLUGIN_AUTH_HOST.
LICENSE_KEY, ORGANIZATION_IDS, REPORTER_URL, CCS_CRYPTO_MASTER_KEY, CIRCUIT_BREAKER_ENABLED=true and OUTBOX_ENABLED=true.
Startup validation checks the license and the TLS posture. A failed check stops the boot.