API Configuration

instance_idstring

InstanceID identifies this particular API server instance. Used in log attribution, Kafka consumer group membership, and cache invalidation messages so that a node can ignore its own broadcasts.

platformstring

Platform identifies the cloud platform where this node runs (e.g. "aws", "gcp", "hetzner", "kubernetes"). Appears in structured logs and metrics labels for filtering by infrastructure.

imagestring

Image is the container image identifier (e.g. "unkey/api:v1.2.3"). Logged at startup for correlating deployments with behavior changes.

http_portinteger

HttpPort is the TCP port the API server binds to. Ignored when Listener is set, which is the case in test harnesses that use ephemeral ports.

Constraints: min: 1, max: 65535

regionstring

Region is the geographic region identifier (e.g. "us-east-1", "eu-west-1"). Included in structured logs and used by the key service when recording which region served a verification request.

redis_urlstring

RedisURL is the connection string for the Redis instance backing distributed rate limiting counters and usage tracking. Example: "redis://redis:6379"

test_modeboolean

TestMode relaxes certain security checks and trusts client-supplied headers that would normally be rejected. This exists for integration tests that need to inject specific request metadata. Do not enable in production.

prometheus_portinteger

PrometheusPort starts a Prometheus /metrics HTTP endpoint on the specified port. Set to 0 (the default) to disable the endpoint entirely.

max_request_body_sizeinteger

MaxRequestBodySize caps incoming request bodies at this many bytes. The zen server rejects requests exceeding this limit with a 413 status. Set to 0 or negative to disable the limit. Defaults to 10 MiB.

database.primary

Required

string

Primary is the MySQL DSN for the read-write database. This is the only required field in the entire configuration because the API server cannot function without a database. Example: "user:pass@tcp(host:3306)/unkey?parseTime=true&interpolateParams=true"

database.readonly_replicastring

ReadonlyReplica is an optional MySQL DSN for a read-replica. When set, read queries are routed here to reduce load on the primary. The connection string format is identical to Primary.

clickhouse.urlstring

URL is the ClickHouse connection string for the shared analytics cluster. When empty, analytics writes are silently discarded. Example: "clickhouse://default:password@clickhouse:9000?secure=false&skip_verify=true"

clickhouse.analytics_urlstring

AnalyticsURL is the base URL for workspace-specific analytics connections. Unlike URL, this endpoint receives per-workspace credentials injected at connection time by the analytics service. Only used when both this field and a [VaultConfig] are configured. Example: "http://clickhouse:8123/default"

clickhouse.proxy_tokenstring

ProxyToken is the bearer token for authenticating against ClickHouse proxy endpoints exposed by the API server itself.

otel.enabledboolean

Enabled activates OpenTelemetry tracing and metrics export to the collector endpoint. Defaults to false.

otel.trace_sampling_ratenumber

TraceSamplingRate is the probability (0.0–1.0) that any given trace is sampled. Lower values reduce overhead in high-throughput deployments. Only meaningful when Enabled is true.

Constraints: min: 0, max: 1

tls.cert_filestring

CertFile is the filesystem path to a PEM-encoded TLS certificate.

tls.key_filestring

KeyFile is the filesystem path to a PEM-encoded TLS private key.

vault.urlstring

URL is the vault service endpoint. Example: "http://vault:8060"

vault.tokenstring

Token is the bearer token used to authenticate with the vault service.

kafka.brokersstring[]

Brokers is the list of Kafka broker addresses. When empty, distributed cache invalidation is disabled and each node operates independently. Example: ["kafka-0:9092", "kafka-1:9092"]

kafka.cache_invalidation_topicstring

CacheInvalidationTopic is the Kafka topic name for broadcasting cache invalidation events between API nodes.

ctrl.urlstring

URL is the CTRL service endpoint. Example: "http://ctrl-api:7091"

ctrl.tokenstring

Token is the bearer token used to authenticate with the CTRL service.

pprof.enabledboolean

Enabled activates pprof profiling endpoints. Defaults to false.

pprof.usernamestring

Username is the Basic Auth username for pprof endpoints. When both Username and Password are empty, pprof endpoints are served without authentication — only appropriate in development environments.

pprof.passwordstring

Password is the Basic Auth password for pprof endpoints.

logging.sample_ratenumber

SampleRate is the baseline probability (0.0–1.0) of emitting a log event that completes faster than SlowThreshold. Set to 1.0 to log everything.

Constraints: min: 0, max: 1

logging.slow_thresholdduration

SlowThreshold is the duration above which a request is considered slow and always logged regardless of SampleRate. Uses Go duration syntax (e.g. "1s", "500ms", "2m30s").