Configuration

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

string

Instance identifier for logs and cache invalidation. Example: "api-7d9b8c4f5d-2kq7m".

string

Platform label for logs and metrics. Example: "aws".

string

Container image identifier logged at startup. Example: "ghcr.io/unkeyed/unkey:v2.0.77".

int

default:"7070"

HTTP server port. Example: 7070.

string

default:"unknown"

Region label for logs and analytics. Example: "us-east-1".

string

required

Redis connection string for counters and usage limiting. Example: "redis://redis:6379".

bool

default:"false"

Enables test-only behaviors. Do not use in production.

int

default:"10485760"

Maximum request size in bytes.

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

string

required

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

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.

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.

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 environments use a JWT template that sets aud to ["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.

bool

default:"true"

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

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.

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.

object

required

MySQL configuration.

Show Fields

string

required

Primary MySQL DSN.

string

Optional read replica DSN.

object

ClickHouse configuration.

Show Fields

string

ClickHouse connection string for shared analytics.

string

Base URL for workspace-specific analytics connections.

object

TLS settings for HTTPS.

Show Fields

bool

Disable TLS when true.

string

Path to TLS certificate.

string

Path to TLS key.

object

Vault connection.

Show Fields

string

Vault base URL.

string

Bearer token for Vault.

object

Control plane connection.

Show Fields

string

required

Control API URL.

string

required

Bearer token for control API.

object

pprof endpoint configuration.

Show Fields

string

required

Basic auth username.

string

required

Basic auth password.

object

Tracing, logging, and metrics configuration.

Show Fields

float

default:"0.25"

Trace sampling rate.

float

default:"1.0"

Log sampling rate.

duration

default:"1s"

Slow log threshold.

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:

env

Region label for logs and traces.

env

required

Redis URL for counters and usage limiting.

env

required

MySQL primary DSN.

env

MySQL read replica DSN.

env

ClickHouse shared URL.

env

ClickHouse analytics base URL.

env

required

Control API URL.

env

required

Control API token.

env

Vault URL.

env

Vault bearer token.

env

pprof username.

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 ["api.unkey.com"], and the auth entry pins audience = "api.unkey.com". Each WorkOS environment (production, canary) must configure this JWT template in the WorkOS dashboard under Authentication settings:

{
  "org": { "id": {{organization.id}} },
  "aud": ["api.unkey.com"]
}

The aud value must be a JSON array. The API parses aud as a string list and rejects tokens that carry it as a bare string, so a string-valued template claim fails verification with “Invalid bearer token”. Without the template, or with a missing aud claim, every forwarded WorkOS access token fails the audience check the same way. 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.

env

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

API base URL that dashboard proxy requests are forwarded to.

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

Overview

Services

RFCs

Configuration model

Environment variables

Dashboard proxy configuration

Example configuration

​Configuration model

​Environment variables

​Dashboard proxy configuration

​Example configuration

​Related docs

Configuration model

Environment variables

Dashboard proxy configuration

Example configuration

Related docs