Configuration reference

Every environment variable the self-hosted io.sign backend reads, with defaults and limits

This page lists the environment variables the io.sign API image reads. Configuration shows a minimum production set and the deployment topology. The webhooks service has its own variables, listed in Webhooks service.

The service validates its configuration when it starts. If a value is missing, malformed, or conflicts with another, the service logs the problem and exits rather than starting with a broken configuration. Boolean variables accept true or false.

🚧

Inject secrets such as DB_PASSWORD, REDIS_PASSWORD, LICENSE_KEY, and JWT_PROVIDERS from your secret manager. Never commit a populated environment file. The service redacts secrets, tokens, keys, passwords, and certificates when it logs its configuration.

Runtime

VariableDefaultDescription
STAGENone. Required.Name of this environment, for example prod. The stages local, dev, test, testing, and build are treated as development stages.
NODE_ENVNoneSet to production.
ORGANISATION_IDA built-in IDYour organisation's ID.

Components and ports

VariableDefaultDescription
ENABLE_ORPCfalseRuns the REST API.
API_PORT3000REST API port.
ENABLE_GRPCfalseRuns the gRPC API, which signers connect to.
ENABLE_GRPC_STREAMfalseEnables the gRPC signing streams. Requires ENABLE_GRPC=true and ENABLE_REDIS=true.
GRPC_PORT50051gRPC API port. HTTP/2 only.
GRPC_TLS_CERT, GRPC_TLS_KEYNoneCertificate and key paths, if you terminate gRPC TLS in the process rather than at a load balancer.
ENABLE_ORCHESTRATORfalseRuns the orchestrator, which coordinates signing sessions. Requires ENABLE_REDIS=true.
ENABLE_CRON_TASKSfalseRuns scheduled tasks, such as expiring requests. Enable it on exactly one replica.
EXPIRE_REQUESTS_CRON_INTERVAL*/10 * * * * *How often the cron task expires requests past their expiresAt, as a cron expression with seconds. The default runs every 10 seconds.

Postgres

The service connects to a writer and, optionally, a read replica. Every writer variable also exists for the reader with a DB_READER_ prefix, for example DB_READER_HOST. The reader is used only when DB_READER_HOST is set. PostgreSQL 17 or later is required.

VariableDefaultDescription
DB_HOSTlocalhostWriter host.
DB_PORT5432Writer port.
DB_NAME, DB_USER, DB_PASSWORDNoneDatabase name and credentials.
DB_SSL_ENABLEDfalseConnects over TLS. Enable it in production.
DB_KEEP_ALIVEfalseEnables TCP keep-alive on connections.
DB_POOL_MIN, DB_POOL_MAX2, 10Connection pool size per process.
DB_STATEMENT_TIMEOUT_MS30000Longest a single statement can run, enforced by Postgres.
DB_QUERY_TIMEOUT_MS35000Longest the service waits for a query, enforced by the driver. Must be greater than DB_STATEMENT_TIMEOUT_MS.
DB_IDLE_IN_TRANSACTION_TIMEOUT_MS60000Longest a transaction can sit idle between statements.
DB_CONNECTION_TIMEOUT_MS10000Longest the service waits for a free connection.
DB_LOG_LEVELerrorSet to query to log every query. Use it for debugging only.

Set any timeout to 0 to disable it. Keep them on in production.

Redis

VariableDefaultDescription
ENABLE_REDISfalseConnects to Redis. Required on every component when the orchestrator runs anywhere in your deployment.
REDIS_HOSTlocalhostRedis host.
REDIS_PORT6379Redis port.
REDIS_PASSWORDNoneRedis password. Omit it if you restrict access at the network layer.

Authentication

See Authentication for how to set these up.

VariableDefaultDescription
JWT_ENABLEDtrueValidates bearer tokens. Never set it to false outside local development.
JWT_PROVIDERSNoneJSON array of identity providers. Each entry has issuer, jwksUri, and optionally audience and algorithms. Required when JWT_ENABLED=true.
JWT_CLOCK_TOLERANCE10Seconds of clock skew allowed when checking token times.

Licence

VariableDefaultDescription
LICENSE_KEYNoneThe licence key io.finnet issued you. Without it, the service runs in read-only mode. See Licensing.

Signer messaging and mobile apps

The service uses these values when its settings table holds no broker setting. A setting stored in the table, for the system or for an organisation, takes precedence. See MQTT broker.

VariableDefaultDescription
SETTINGS_DEFAULT_MQTT_BROKER_URLwss://localhost:8084/mqttThe MQTT broker URL that signers connect to.
SETTINGS_DEFAULT_MQTT_BROKER_CERTIFICATEEmptyThe broker's certificate, if signers need it to trust the broker.

The public app configuration that Mobile Signers read at GET /v2/app/config comes from the APP_CONFIG_* variables. See Public app configuration for Mobile Signers.

Push notifications

Each category is on by default. Set one to false to stop Mobile Signers receiving that notification.

VariableNotification
PUSH_CATEGORY_SIGNATURE_VOTE_NEEDED_ENABLEDA signature request needs the signer's approval.
PUSH_CATEGORY_KEYGEN_VOTE_NEEDED_ENABLEDA new vault needs the signer's approval.
PUSH_CATEGORY_RESHARE_VOTE_NEEDED_ENABLEDA reshare needs the signer's approval.
PUSH_CATEGORY_SIGNER_OFFLINE_MID_CEREMONY_ENABLEDThe signer went offline during signing.
PUSH_CATEGORY_REQUEST_COMPLETED_SUCCESSFULLY_ENABLEDA request completed.
PUSH_CATEGORY_REQUEST_UNSUCCESSFUL_ENABLEDA request didn't complete.

Signing

VariableDefaultDescription
MAX_SIGNING_ATTEMPTS3How many times the orchestrator attempts a signing session before the request fails. A system-wide or organisation setting in the settings table overrides it.
VAULT_MAX_THRESHOLD25Highest threshold a vault can have. Must be between 10 and 50.
SINGLE_CONNECTION_PER_SIGNERfalseRefuses a second signing connection from a signer that is already connected.

Request limits

VariableDefaultDescription
API_VALIDATION_MAX_DATA_ENTRIES20Most dataToSign entries in one signature request.
API_VALIDATION_MAX_DATA_LENGTH80000Longest dataToSign entry, in characters.
API_VALIDATION_MAX_METADATA_SIZE100000Largest request metadata, in characters.
API_VALIDATION_SERIALIZED_DATA_MODEenforceHow the service checks a request's serialised transaction against its contextType. enforce rejects a mismatch, warn logs it, and off skips the check. An organisation setting can override it.

Idempotency

VariableDefaultDescription
IDEMPOTENCY_PROCESSING_TTL_MS600000How long a request with an idempotency-key blocks a retry while it is still being processed. Must be less than IDEMPOTENCY_COMPLETED_TTL_MS.
IDEMPOTENCY_COMPLETED_TTL_MS86400000How long the service replays a completed response for the same key.
IDEMPOTENCY_MAX_KEY_LENGTH50Longest key accepted.

Events

io.sign publishes events to subscribers such as the webhooks service. Delivery is at least once, so a consumer can receive the same event more than once.

Audit

VariableDefaultDescription
AUDIT_TRUSTED_PROXY_CIDRSNoneComma-separated IP addresses or CIDR ranges of the load balancers and proxies in front of the API. See Record client IP addresses.

Logging and telemetry

See Logging and observability for the OpenTelemetry variables.

VariableDefaultDescription
LOG_LEVELinfoLog level: trace, debug, info, warn, error, or fatal.
LOG_PRETTYfalsePrints readable logs instead of JSON. Use it locally only.
HTTP_LOG_MAX_BODY_BYTES65536Longest request or response body included in HTTP logs.
OTEL_EVENT_PROPAGATIONfalseCarries trace context through internal events, so traces follow a request across components.

Did this page help you?