Skip to main content

​
Configuration model

Unkey services read configuration from a TOML file passed at startup. Environment variables can be referenced with ${VAR} and are expanded before parsing. Defaults and validation run after parsing. The config schema maps to svc/api/config.go. Minimal config example: 
instance_id = "${POD_NAME}"
platform = "aws"
http_port = 7070
region = "${UNKEY_REGION}"
redis_url = "${UNKEY_REDIS_URL}"

[database]
primary = "${UNKEY_DATABASE_PRIMARY}"
readonly_replica = "${UNKEY_DATABASE_REPLICA}"

[clickhouse]
url = "${UNKEY_CLICKHOUSE_URL}"
analytics_url = "${UNKEY_CLICKHOUSE_ANALYTICS_URL}"

[control]
url = "${UNKEY_CTRL_URL}"
token = "${UNKEY_CTRL_TOKEN}"

[vault]
url = "${UNKEY_VAULT_URL}"
token = "${UNKEY_VAULT_TOKEN}"
​
instance_id
string
Instance identifier for logs and cache invalidation. Example: "api-7d9b8c4f5d-2kq7m".
​
platform
string
Platform label for logs and metrics. Example: "aws".
​
image
string
Container image identifier logged at startup. Example: "ghcr.io/unkeyed/unkey:v2.0.77".
​
http_port
int
default:"7070"
HTTP server port. Example: 7070.
​
region
string
default:"unknown"
Region label for logs and analytics. Example: "us-east-1".
​
redis_url
string
required
Redis connection string for counters and usage limiting. Example: "redis://redis:6379".
​
test_mode
bool
default:"false"
Enables test-only behaviors. Do not use in production.
​
max_request_body_size
int
default:"10485760"
Maximum request size in bytes.
​
database
object
required
MySQL configuration.
​
clickhouse
object
ClickHouse configuration.
​
tls
object
TLS settings for HTTPS.
​
vault
object
Vault connection.
​
gossip
object
Gossip-based cache invalidation.
​
control
object
Control plane connection.
​
pprof
object
pprof endpoint configuration.
​
observability
object
Tracing, logging, and metrics configuration.

​
Environment variables

The Helm chart provides these variables for the default config template:
​
UNKEY_REGION
env
Region label for logs and traces.
​
UNKEY_REDIS_URL
env
required
Redis URL for counters and usage limiting.
​
UNKEY_DATABASE_PRIMARY
env
required
MySQL primary DSN.
​
UNKEY_DATABASE_REPLICA
env
MySQL read replica DSN.
​
UNKEY_CLICKHOUSE_URL
env
ClickHouse shared URL.
​
UNKEY_CLICKHOUSE_ANALYTICS_URL
env
ClickHouse analytics base URL.
​
UNKEY_CTRL_URL
env
required
Control API URL.
​
UNKEY_CTRL_TOKEN
env
required
Control API token.
​
UNKEY_VAULT_URL
env
Vault URL.
​
UNKEY_VAULT_TOKEN
env
Vault bearer token.
​
UNKEY_PPROF_USERNAME
env
pprof username.
​
UNKEY_PPROF_PASSWORD
env
pprof password.
​
UNKEY_GOSSIP_WAN_SEEDS
env
WAN seed list for gossip.
​
UNKEY_GOSSIP_SECRET_KEY
env
required
Gossip secret key.

​
Example configuration

instance_id = "${POD_NAME}"
platform = "aws"
http_port = 7070
region = "${UNKEY_REGION}"
redis_url = "${UNKEY_REDIS_URL}"

[observability.tracing]
sample_rate = 0.1

[observability.logging]
sample_rate = 0.01
slow_threshold = "1s"

[observability.metrics]
prometheus_port = 2112

[database]
primary = "${UNKEY_DATABASE_PRIMARY}"
readonly_replica = "${UNKEY_DATABASE_REPLICA}"

[clickhouse]
url = "${UNKEY_CLICKHOUSE_URL}"
analytics_url = "${UNKEY_CLICKHOUSE_ANALYTICS_URL}"

[control]
url = "${UNKEY_CTRL_URL}"
token = "${UNKEY_CTRL_TOKEN}"

[vault]
url = "${UNKEY_VAULT_URL}"
token = "${UNKEY_VAULT_TOKEN}"

[pprof]
username = "${UNKEY_PPROF_USERNAME}"
password = "${UNKEY_PPROF_PASSWORD}"

[gossip]
lan_port = 7946
wan_port = 7947
lan_seeds = ["unkey-api-gossip-lan"]
wan_seeds = ["${UNKEY_GOSSIP_WAN_SEEDS}"]
secret_key = "${UNKEY_GOSSIP_SECRET_KEY}"