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, andJWT_PROVIDERSfrom your secret manager. Never commit a populated environment file. The service redacts secrets, tokens, keys, passwords, and certificates when it logs its configuration.
Runtime
| Variable | Default | Description |
|---|---|---|
STAGE | None. Required. | Name of this environment, for example prod. The stages local, dev, test, testing, and build are treated as development stages. |
NODE_ENV | None | Set to production. |
ORGANISATION_ID | A built-in ID | Your organisation's ID. |
Components and ports
| Variable | Default | Description |
|---|---|---|
ENABLE_ORPC | false | Runs the REST API. |
API_PORT | 3000 | REST API port. |
ENABLE_GRPC | false | Runs the gRPC API, which signers connect to. |
ENABLE_GRPC_STREAM | false | Enables the gRPC signing streams. Requires ENABLE_GRPC=true and ENABLE_REDIS=true. |
GRPC_PORT | 50051 | gRPC API port. HTTP/2 only. |
GRPC_TLS_CERT, GRPC_TLS_KEY | None | Certificate and key paths, if you terminate gRPC TLS in the process rather than at a load balancer. |
ENABLE_ORCHESTRATOR | false | Runs the orchestrator, which coordinates signing sessions. Requires ENABLE_REDIS=true. |
ENABLE_CRON_TASKS | false | Runs 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.
| Variable | Default | Description |
|---|---|---|
DB_HOST | localhost | Writer host. |
DB_PORT | 5432 | Writer port. |
DB_NAME, DB_USER, DB_PASSWORD | None | Database name and credentials. |
DB_SSL_ENABLED | false | Connects over TLS. Enable it in production. |
DB_KEEP_ALIVE | false | Enables TCP keep-alive on connections. |
DB_POOL_MIN, DB_POOL_MAX | 2, 10 | Connection pool size per process. |
DB_STATEMENT_TIMEOUT_MS | 30000 | Longest a single statement can run, enforced by Postgres. |
DB_QUERY_TIMEOUT_MS | 35000 | Longest the service waits for a query, enforced by the driver. Must be greater than DB_STATEMENT_TIMEOUT_MS. |
DB_IDLE_IN_TRANSACTION_TIMEOUT_MS | 60000 | Longest a transaction can sit idle between statements. |
DB_CONNECTION_TIMEOUT_MS | 10000 | Longest the service waits for a free connection. |
DB_LOG_LEVEL | error | Set 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
| Variable | Default | Description |
|---|---|---|
ENABLE_REDIS | false | Connects to Redis. Required on every component when the orchestrator runs anywhere in your deployment. |
REDIS_HOST | localhost | Redis host. |
REDIS_PORT | 6379 | Redis port. |
REDIS_PASSWORD | None | Redis password. Omit it if you restrict access at the network layer. |
Authentication
See Authentication for how to set these up.
| Variable | Default | Description |
|---|---|---|
JWT_ENABLED | true | Validates bearer tokens. Never set it to false outside local development. |
JWT_PROVIDERS | None | JSON array of identity providers. Each entry has issuer, jwksUri, and optionally audience and algorithms. Required when JWT_ENABLED=true. |
JWT_CLOCK_TOLERANCE | 10 | Seconds of clock skew allowed when checking token times. |
Licence
| Variable | Default | Description |
|---|---|---|
LICENSE_KEY | None | The 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.
| Variable | Default | Description |
|---|---|---|
SETTINGS_DEFAULT_MQTT_BROKER_URL | wss://localhost:8084/mqtt | The MQTT broker URL that signers connect to. |
SETTINGS_DEFAULT_MQTT_BROKER_CERTIFICATE | Empty | The 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.
| Variable | Notification |
|---|---|
PUSH_CATEGORY_SIGNATURE_VOTE_NEEDED_ENABLED | A signature request needs the signer's approval. |
PUSH_CATEGORY_KEYGEN_VOTE_NEEDED_ENABLED | A new vault needs the signer's approval. |
PUSH_CATEGORY_RESHARE_VOTE_NEEDED_ENABLED | A reshare needs the signer's approval. |
PUSH_CATEGORY_SIGNER_OFFLINE_MID_CEREMONY_ENABLED | The signer went offline during signing. |
PUSH_CATEGORY_REQUEST_COMPLETED_SUCCESSFULLY_ENABLED | A request completed. |
PUSH_CATEGORY_REQUEST_UNSUCCESSFUL_ENABLED | A request didn't complete. |
Signing
| Variable | Default | Description |
|---|---|---|
MAX_SIGNING_ATTEMPTS | 3 | How 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_THRESHOLD | 25 | Highest threshold a vault can have. Must be between 10 and 50. |
SINGLE_CONNECTION_PER_SIGNER | false | Refuses a second signing connection from a signer that is already connected. |
Request limits
| Variable | Default | Description |
|---|---|---|
API_VALIDATION_MAX_DATA_ENTRIES | 20 | Most dataToSign entries in one signature request. |
API_VALIDATION_MAX_DATA_LENGTH | 80000 | Longest dataToSign entry, in characters. |
API_VALIDATION_MAX_METADATA_SIZE | 100000 | Largest request metadata, in characters. |
API_VALIDATION_SERIALIZED_DATA_MODE | enforce | How 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
| Variable | Default | Description |
|---|---|---|
IDEMPOTENCY_PROCESSING_TTL_MS | 600000 | How 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_MS | 86400000 | How long the service replays a completed response for the same key. |
IDEMPOTENCY_MAX_KEY_LENGTH | 50 | Longest 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
| Variable | Default | Description |
|---|---|---|
AUDIT_TRUSTED_PROXY_CIDRS | None | Comma-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.
| Variable | Default | Description |
|---|---|---|
LOG_LEVEL | info | Log level: trace, debug, info, warn, error, or fatal. |
LOG_PRETTY | false | Prints readable logs instead of JSON. Use it locally only. |
HTTP_LOG_MAX_BODY_BYTES | 65536 | Longest request or response body included in HTTP logs. |
OTEL_EVENT_PROPAGATION | false | Carries trace context through internal events, so traces follow a request across components. |
Updated 17 days ago