Server Configuration¶

SigID is configured through a TOML file (typically sigid.toml). A complete, commented example is shipped as [sigid.example.toml][] in the repository root. This page summarizes the major sections and explains production hardening requirements.

Server and networking¶

The [server] section controls the HTTP listener, TLS, CORS, and proxy trust.

Setting	Purpose
`host`, `port`	Listen address and port
`transport`	`"tls_h2_only"` (required; terminates TLS in-process, requires ALPN h2)
`base_domain`	Primary domain for cookie scoping
`cors_allowed_origins`	Allowed browser origins; empty falls back to issuer origin
`trusted_proxies`	IP addresses and CIDRs allowed to send `X-Forwarded-For`
`allowed_hosts`	Host-header allowlist; requests with non-matching hosts are rejected

When using transport = "tls_h2_only", configure [server.tls] with cert_pem_path and key_pem_path. Set ca_pem_path when local clients such as container health checks need an explicit trust bundle for the direct listener.

Database¶

The [database] section configures the primary PostgreSQL connection and optional split-plane URLs.

Setting	Purpose
`url`	Primary connection string
`identity_url`, `auth_url`, `control_url`, `async_url`	Dedicated URLs for specific planes
`maintenance_url`, `migration_url`	Privileged connection strings
`max_connections`, `min_connections`	Pool sizing
`connect_timeout_secs`	Connection timeout

For production, set require_ssl = true for non-local database connections.

Security and KMS¶

The [security] section controls production mode and webhook safety.

Setting	Purpose
`production`	Must be `true` for non-localhost deployments
`webhook_allow_non_standard_ports`	Allow webhook delivery to non-443 ports (default: `false`)

When production = true, the system requires the [kms] section to be configured (see Production mode below).

JWT¶

The [jwt] section configures token signing and lifetimes.

Setting	Default	Purpose
`default_algorithm`	`"ES256"`	Signing algorithm (`"ES256"` or `"EdDSA"`)
`access_token_lifetime_human_secs`	900	Human access token lifetime
`access_token_lifetime_agent_secs`	300	Agent access token lifetime
`refresh_token_lifetime_human_secs`	604800	Human refresh token lifetime
`refresh_token_lifetime_agent_secs`	86400	Agent refresh token lifetime
`key_rotation_days`	30	Signing key rotation period

Authentication and rate limiting¶

The [auth] section controls password hashing, brute-force protection, and registration rate limits.

Setting	Purpose
`argon2_memory_kib`	Argon2 memory cost
`argon2_iterations`, `argon2_parallelism`	Argon2 time and parallelism
`brute_force_max_attempts`	Failed login attempts before lockout
`brute_force_lockout_secs`	Lockout duration
`password_verify_ip_*`	IP-weighted budget for expensive password verification
`registration_rate_limit_*`	Registration rate limiting

OIDC issuer¶

The [oidc] section defines the issuer URL and authorization code lifetime. When server.transport = "tls_h2_only", the issuer URL must use https://.

Email delivery¶

The [email] section configures transactional email (verification, password reset, magic links, OTP). Set provider to "smtp" or "http_api" and configure the corresponding [email.smtp] or [email.http_api] subsection.

Section	Purpose
`[social]`	Global social OAuth settings and per-provider configuration
`[enterprise_sso]`	Enterprise OIDC SSO state secret and caching
`[generic_oauth]`	Database-backed arbitrary OAuth/OIDC providers

Passkeys and WebAuthn¶

The [passkey] section sets the relying party ID, name, and expected origin. In production, the origin must use https://.

Additional sections¶

Section	Purpose
`[phone]`, `[sms]`	Phone/SMS OTP delivery
`[email_otp]`	Email OTP settings
`[magic_link]`	Magic link passwordless authentication
`[anonymous]`	Anonymous/guest authentication with TTL for unconverted users
`[two_factor]`	TOTP, backup codes, trusted devices
`[adaptive_mfa]`	Risk-based step-up authentication
`[challenge]`	Challenge nonce TTL, agent PoW difficulty, agent limits
`[captcha]`	Cloudflare Turnstile, reCAPTCHA, hCaptcha
`[hibp]`	HaveIBeenPwned breach checking
`[device_authorization]`	RFC 8628 device flow
`[session_cookie]`	Session limits, cache cookies, binding
`[admin]`	Admin panel roles and bootstrap admin user credentials
`[access_control]`	RBAC/ABAC role, policy, and scope limits
`[proxy]`	Outbound proxy mTLS (sigid-proxy)
`[oauth_proxy]`	Development-only OAuth proxy for redirect callbacks
`[wallet]`	Managed wallet signing
`[[chains]]`	Blockchain RPC configuration
`[siwe]`	Sign-In with Ethereum (EIP-4361)
`[api_keys]`	API key authentication
`[i18n]`	Localization and message catalogs
`[openapi]`	OpenAPI documentation endpoints (disabled in production)
`[billing]`	Subscription plan billing, usage snapshots, and reconciliation
`[commerce]`	Tenant-facing Stripe commerce and payment-of-record
`[dpop]`	DPoP (RFC 9449) sender-constrained token proof validation
`[organizations]`	Multi-tenant team/workspace system
`[invitations]`	Organization invitation expiry and bulk limits
`[verified_domains]`	Custom domain DNS verification and revalidation
`[vault]`	Credential storage limits
`[webhooks]`	Webhook subscription limits
`[scim]`	SCIM 2.0 provisioning
`[telemetry]`	Auth-specific metrics and tracing
`[deployment]`	Deployment topology, coordination backend, plane selection
`[refresh_family_cache]`	Refresh-token family revocation cache TTL and capacity
`[user_self_service]`	Account deletion, password change behavior

Environment variable overrides¶

SigID supports environment variable overrides for database URLs and deployment topology. Environment variables take precedence over the TOML file.

Runtime plane selection¶

For split-plane deployments, set SIGID_RUNTIME_PLANE to select which routes and workers the process handles:

Value	Purpose
`auth`	Authentication and session routes
`control`	Management API and admin routes
`async`	Background workers and event processing

Database URL overrides¶

These environment variables override the corresponding TOML database URLs, regardless of which TOML section they are defined in:

Variable	TOML equivalent
`DATABASE_IDENTITY_URL`	`[database].identity_url`
`DATABASE_AUTH_URL`	`[database].auth_url`
`DATABASE_CONTROL_URL`	`[database].control_url`
`DATABASE_ASYNC_URL`	`[database].async_url`
`MAINTENANCE_DATABASE_URL`	`[database].maintenance_url`
`MIGRATION_DATABASE_URL`	`[database].migration_url`

Plane-specific pool overrides¶

The [database.auth_pool], [database.control_pool], and [database.async_pool] sections override pool sizing when SIGID_RUNTIME_PLANE matches the corresponding plane.

Database migrations¶

Migrations run as a separate initialization step:

sigid-runtime --migrate-only

Production mode¶

When deploying to non-localhost origins, security.production must be set to true. The system will refuse to start if non-local deployment indicators (such as non-loopback URLs) are detected without production mode enabled.

Enabling production mode requires the following companion settings:

Setting	Section	Purpose
`socket_path`, `server_public_key_path`, `client_private_key_path`	`[kms]`	Key management service client
`trusted_proxies`	`[server]`	IPs allowed to send `X-Forwarded-For`
`allowed_hosts`	`[server]`	Permitted Host-header values
`cert_pem_path`, `key_pem_path`	`[server.tls]`	TLS certificate and key
`require_ssl`	`[database]`	Enforce SSL for database connections

Production hardening checklist¶

Before exposing SigID to production traffic, verify:

security.production = true
[kms] client is configured and the KMS daemon is reachable
server.transport = "tls_h2_only" is set (the only supported transport mode)
trusted_proxies lists only known infrastructure IPs
allowed_hosts lists only expected domain names
Database connections require SSL
The OIDC issuer URL uses https://
Passkey origin uses https://
Outbound proxy is configured for external calls (social login, HIBP, captcha)
webhook_allow_non_standard_ports is false
Email delivery is configured with a production provider

This server-level checklist complements the tenant-level production checklist and the security controls documented elsewhere.