Configuration - engineering

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.

auth

object[]

required

Ordered authentication resolver configuration. Each entry registers one auth mechanism. At least one entry is required: a config without auth entries would reject every request, including valid root keys, so startup fails instead.

Show Fields

auth.type

string

required

Auth mechanism. Supported values are jwt, portal_session, and root_key.

auth.issuer

string

Expected JWT iss claim. Required for type = "jwt" entries and rejected as an unknown field on portal_session and root_key entries. The issuer does not affect permission translation; set auth.provider to opt into WorkOS slug translation.

auth.provider

string

Permission dialect carried by this entry’s tokens for type = "jwt". Leave unset when tokens already carry canonical Unkey permissions. Set provider = "workos" to translate WorkOS permission slugs into canonical Unkey permissions after verification. Translation is selected by this field, not inferred from the issuer, so any issuer (including custom auth domains) can opt in the same way.

auth.audience

string

Optional expected JWT aud claim for type = "jwt". Verification requires the configured value to appear in the token’s aud list. The Unkey WorkOS environment uses a JWT template that sets aud to ["app.unkey.com", "api.unkey.com"], so set audience = "api.unkey.com" on the WorkOS entry. Omit this field only for providers that do not emit an audience claim. Setting it rejects tokens without a matching aud, so when introducing the claim, add it to the provider’s token template first, wait for tokens minted without it to expire, then set this field.

auth.enabled

bool

default:"true"

Optional explicit enable flag. false is invalid; remove the auth entry instead.

auth.secrets

string[]

Ordered JWT verification secrets for type = "jwt". During rotation, put the active signing secret first and keep retired secrets later in the list until every token signed with those secrets has expired. Configure either secrets or jwks_url, never both.

auth.jwks_url

string

JWKS endpoint for type = "jwt". Must be an absolute https URL so signing keys cannot be substituted over an unauthenticated channel. The API fetches the JSON Web Key Set on first use and verifies incoming JWTs against usable RSA signing keys from the response. When a token fails verification against every cached key, the key set is refetched (rate limited to once per minute), so signing-key rotations are picked up without a restart. Configure either jwks_url or secrets, never both.

database

object

required

MySQL configuration.

Show Fields

database.primary

string

required

Primary MySQL DSN.

database.readonly_replica

string

Optional read replica DSN.

clickhouse

object

ClickHouse configuration.

Show Fields

clickhouse.url

string

ClickHouse connection string for shared analytics.

clickhouse.analytics_url

string

Base URL for workspace-specific analytics connections.

tls

object

TLS settings for HTTPS.

Show Fields

tls.disabled

bool

Disable TLS when true.

tls.cert_file

string

Path to TLS certificate.

tls.key_file

string

Path to TLS key.

vault

object

Vault connection.

Show Fields

vault.url

string

Vault base URL.

vault.token

string

Bearer token for Vault.

control

object

Control plane connection.

Show Fields

control.url

string

required

Control API URL.

control.token

string

required

Bearer token for control API.

pprof

object

pprof endpoint configuration.

Show Fields

pprof.username

string

required

Basic auth username.

pprof.password

string

required

Basic auth password.

observability

object

Tracing, logging, and metrics configuration.

Show Fields

observability.tracing.sample_rate

float

default:"0.25"

Trace sampling rate.

observability.logging.sample_rate

float

default:"1.0"

Log sampling rate.

observability.logging.slow_threshold

duration

default:"1s"

Slow log threshold.

observability.metrics.prometheus_port

int

default:"0"

Prometheus port for the /metrics listener. To disable metrics, omit the observability.metrics section.

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.

Dashboard proxy configuration

The dashboard proxy forwards the WorkOS access token when a WorkOS session is available. The API verifies that token through a type = "jwt" auth entry configured with the WorkOS issuer and JWKS URL. The WorkOS JWT template includes the organization as org.id, and the API reads Unkey RBAC permissions from the token’s permissions claim. The template also sets aud to ["app.unkey.com", "api.unkey.com"], and the auth entry pins audience = "api.unkey.com". Local development still uses a dashboard-minted fallback JWT when no WorkOS access token exists. For that path, the dashboard needs a signing secret and the API must include the same secret in a type = "jwt" auth entry. The local fallback JWT includes the dashboard proxy permission set directly, so every local dashboard user is effectively an API admin.

UNKEY_API_URL

env

default:"https://api.unkey.com"

API base URL that dashboard proxy requests are forwarded to.

UNKEY_JWT_SECRET

env

Local dashboard proxy signing secret. Add the same value to the API JWT auth entry’s secrets list so the API can verify dashboard-minted fallback JWTs.

Example configuration

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

[[auth]]
type = "jwt"
issuer = "https://api.workos.com"
audience = "api.unkey.com"
jwks_url = "${UNKEY_JWT_JWKS_URL}"
provider = "workos"

[[auth]]
type = "portal_session"

[[auth]]
type = "root_key"
enabled = true

[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}"

Overview

​Configuration model

​Environment variables

​Dashboard proxy configuration

​Example configuration

​Related docs

Configuration model

Environment variables

Dashboard proxy configuration

Example configuration

Related docs