EDI Configuration

Configure shared storage, authentication, encrypted connections, event delivery, transport policy, and current retention.

Use the source .env.example and deployment secret references for the full environment contract. The settings below cover common operating decisions. The integration variable EDI_API_TOKEN in client examples contains a scoped key; the same-named server setting is the platform administrator token.

Core and storage

Variable	Default	Purpose
EDI_BIND_ADDR	0.0.0.0:8480	HTTP listener; terminate public TLS at a trusted proxy
EDI_API_TOKEN	required	Server platform administrator credential
EDI_AUTH_DISABLED	false	Development-only unauthenticated operation
EDI_ALLOW_INSECURE_AUTH_DISABLED	false	Additional explicit opt-in for unauthenticated Kubernetes
DATABASE_URL	unset	PostgreSQL for shared stores and durable outbound receipts
EDI_MIGRATE_ON_START	false	Normally run a separate migration Job; local single-instance opt-in
EDI_PG_POOL_MAX_CONNECTIONS	25	Per-replica connection ceiling
EDI_DATA_DIR	./data	File-backed development state
EDI_ALLOW_FILE_STORAGE	false	Explicit single-instance Kubernetes file-storage exception
EDI_CONNECTION_ENCRYPTION_KEY	unset	32-byte hex key for stored connection/callback secrets
EDI_GATEWAY_TOKEN	unset	Separate gateway HMAC secret, at least 32 characters
EDI_REQUIRE_PRODUCTION_READINESS	true	Enforce current evidence for production partners
EDI_CORS_ORIGINS	unset	Explicit browser-origin allowlist; unset means same-origin
EDI_CORS_ALLOW_ANY	false	Required to permit wildcard CORS
EDI_RATE_LIMIT_RPM	600	Per-client budget; 0 disables
EDI_TRUSTED_PROXY_HOPS	0	Trusted proxy hops; 0 ignores forwarded IP headers

Multiple replicas require PostgreSQL. File stores and control-number/dedup state otherwise diverge. Directory/VAN paths with PostgreSQL additionally require a shared persistent mount and EDI_FILE_TRANSPORT_SHARED=true. Retain encryption/signing/transport keys alongside recoverable database backups; ciphertext alone cannot resume pending work.

Event destinations

Variable	Purpose
STATESET_SEQUENCER_URL	Sequencer base; source default https://api.sequencer.stateset.com/v1
STATESET_API_KEY	Sequencer credential enabling its event sink
STATESET_SYNC_SERVER_URL	Optional platform Sync event destination
STATESET_EDI_WEBHOOK_SECRET	Required HMAC secret for that Sync destination
STATESET_EDI_DEFAULT_TENANT_ID	Legacy fallback; leave unset for normal multi-tenant operation
EDI_FLUSH_SECONDS	Automatic flush interval, default 30; 0 disables

Customer Sync bindings in Connections carry tenant/environment-specific revisions. A configured sink or successful setup probe does not establish ERP acceptance. Verify signed delivery, duplicate handling, and actual downstream objects.

Event delivery signing

These are three different protocols. Verify exact bytes and the relevant timestamp policy.

Path	Headers	HMAC-SHA256 input / output
Operational alerts / lead forwarding	X-Stateset-Signature	Raw body; sha256=<hex>
Platform Sync event delivery	x-stateset-edi-timestamp, x-stateset-edi-signature	Timestamp + . + raw body; sha256=<hex>
Customer document callbacks	x-stateset-timestamp, x-stateset-event-id, x-stateset-key-version, x-stateset-signature	Timestamp + . + event ID + . + raw body; v1=<hex>

Timestamped receivers must enforce a bounded time window, verify before parsing, and persist stable event identity for duplicate handling. Do not substitute one signature scheme for another. The callback SDK helper verifies the customer-callback scheme; it is not a Sync-signature verifier.

Transports and cryptography

Settings	Purpose
EDI_AS2_KEY_FILE, EDI_AS2_CERT_FILE	OpenSSL-backed S/MIME identity
EDI_AS2_REQUIRE_VERIFIED_INBOUND=true	Require verified inbound AS2
EDI_AS2_PERSIST_IDENTITY=false	Runtime rotation is replica-local unless persisted
EDI_DELIVERY_POLL_SECONDS=60	AS2 delivery scan; 0 disables
EDI_MDN_TIMEOUT_HOURS=24	Async receipt deadline
EDI_AUTO_ACK_POLL_SECONDS=1	Durable automatic-855 worker; 0 disables
EDI_INBOUND_DIR, EDI_OUTBOUND_DIR, EDI_VAN_ROOT	Platform directory/VAN paths
EDI_SFTP_*	Legacy platform connector; tenant connections use stored revisions
EDI_SFTP_ALLOWED_PRIVATE_HOSTS, EDI_FTPS_ALLOWED_PRIVATE_HOSTS	Exact allowed private hosts for tenant connections
EDI_MAIL_API_URL, EDI_MAIL_API_KEY, EDI_MAIL_FROM	Platform Mail settings; tenant setup uses managed/BYOS connections
EDI_GS1_COMPANY_PREFIX	Owned GS1 prefix for SSCC allocation
EDI_SSCC_PARTNER_MAX_COUNT=10	Per-request partner-key allocation ceiling
EDI_SIGNING_KEY, EDI_SIGNING_KEY_ID	Event signing seed/identity; unset seed is generated and persisted
EDI_SIGNING_KEY_COMMAND, EDI_SIGNING_PUBLIC_KEY	External signing command/key discovery
EDI_SIGNING_STRICT=true	Fail closed on event-signing failure

See transports for supported profiles and receipt boundaries. Never treat an allowlisted private host as proof of partner ownership or network isolation.

Monitoring and retention

EDI_LOG_FORMAT=json enables structured logs. RUST_LOG controls levels; OTEL_EXPORTER_OTLP_ENDPOINT enables OTLP traces. Protect telemetry containing identifiers. Alert channels use EDI_ALERT_WEBHOOK_URL, optional EDI_ALERT_WEBHOOK_SECRET, and EDI_ALERT_EMAIL_TO with the Mail connector. EDI_ALERT_THROTTLE_SECONDS defaults to 300, EDI_ACK_SLA_HOURS to 24, and EDI_CERT_EXPIRY_WARN_DAYS to 21.

Current retention defaults are 400 days for documents, usage, dedup, and settled acknowledgments; 180 for terminal deliveries; 90 for eligible dead letters. Each has a corresponding EDI_*_RETENTION_DAYS setting; 0 disables that sweep. See retention details before choosing a replay window or offboarding policy. Review deployment qualification for migrations, compatible rollback, and backup evidence.