Configuration reference

This page is auto-generated from the configuration schema.

Required top-level keys: credentials, secrets

Environment variables

Every configuration key can be set via an environment variable. Ory Talos converts dot-separated config paths to uppercase with underscores:

<SECTION>_<KEY>

Replace dots (.) with underscores (_) and convert to uppercase. For example, serve.http.port becomes SERVE_HTTP_PORT.

Array values

For array-typed config keys (like secrets.hmac.retired), use comma separation or indexed variables:

# Comma-separated
export SECRETS_HMAC_RETIRED="old-secret-1,old-secret-2"

# Or indexed
export SECRETS_HMAC_RETIRED_0="old-secret-1"
export SECRETS_HMAC_RETIRED_1="old-secret-2"

Precedence

Configuration sources are applied in this order (highest priority first):

1. Environment variables
2. Configuration file (--config flag)
3. Default values

Environment variables always override file-based configuration.

Required variables

At minimum, these must be set (via env var or config file):

Variable	Description
SECRETS_HMAC_CURRENT	HMAC secret (also derives the pagination cursor key). Minimum 32 characters.
CREDENTIALS_ISSUER	Token issuer (iss claim) for derived tokens.

cache Commercial

Cache configuration.

Key	Type	Default	Env Var	Description
cache.memory.max_size	integer	104857600	CACHE_MEMORY_MAX_SIZE	Maximum memory usage in bytes. (restart required, Commercial)
cache.memory.num_counters	integer	10000	CACHE_MEMORY_NUM_COUNTERS	Number of counters for frequency estimation. (restart required, Commercial)
cache.redis.addrs	string[]	["localhost:6379"]	CACHE_REDIS_ADDRS	Redis server addresses (supports cluster/sentinel). (restart required, Commercial)
cache.redis.conn_max_idle_time	string	5m	CACHE_REDIS_CONN_MAX_IDLE_TIME	Maximum duration a connection may be idle before being closed. (restart required, Commercial)
cache.redis.conn_max_lifetime	string	30m	CACHE_REDIS_CONN_MAX_LIFETIME	Maximum duration a connection may be reused. (restart required, Commercial)
cache.redis.db	integer	0	CACHE_REDIS_DB	Redis database number. (restart required, Commercial)
cache.redis.min_idle_conns	integer	2	CACHE_REDIS_MIN_IDLE_CONNS	Minimum number of idle connections kept open. (restart required, Commercial)
cache.redis.password	string	—	CACHE_REDIS_PASSWORD	Redis password. (restart required, Commercial)
cache.redis.pool_size	integer	100	CACHE_REDIS_POOL_SIZE	Connection pool size. (restart required, Commercial)
cache.redis.timeout	string	3s	CACHE_REDIS_TIMEOUT	Redis operation timeout (duration string). (restart required, Commercial)
cache.redis.tls.enabled	boolean	false	CACHE_REDIS_TLS_ENABLED	Enable TLS using the system certificate pool. (restart required, Commercial)
cache.ttl	string	5m	CACHE_TTL	Default cache TTL (duration string). (Commercial)
cache.type	memory, redis, noop	noop	CACHE_TYPE	Cache implementation type. (restart required, Commercial)

credentials

Credential configuration for API keys and derived tokens (JWT, macaroon).

Key	Type	Default	Env Var	Description
credentials.api_keys.default_ttl	string	—	CREDENTIALS_API_KEYS_DEFAULT_TTL	Default API key TTL (duration string).
credentials.api_keys.max_ttl	string	8760h	CREDENTIALS_API_KEYS_MAX_TTL	Maximum age for API keys with timestamps.
credentials.api_keys.prefix.current	string	ory_ak	CREDENTIALS_API_KEYS_PREFIX_CURRENT	Current prefix used for new API key generation.
credentials.api_keys.prefix.public_current	string	—	CREDENTIALS_API_KEYS_PREFIX_PUBLIC_CURRENT	Current prefix used for new PUBLIC API key generation.
credentials.api_keys.prefix.public_retired	string[]	[]	CREDENTIALS_API_KEYS_PREFIX_PUBLIC_RETIRED	Retired public prefixes accepted during verification for migration purposes.
credentials.api_keys.prefix.retired	string[]	[]	CREDENTIALS_API_KEYS_PREFIX_RETIRED	Retired prefixes accepted during verification for migration purposes.
credentials.clock_skew	string	5m	CREDENTIALS_CLOCK_SKEW	Maximum clock skew tolerance for timestamp and token validation.
credentials.derived_tokens.default_ttl	string	1h	CREDENTIALS_DERIVED_TOKENS_DEFAULT_TTL	Default derived token TTL applied to both JWT and macaroon tokens when no explicit TTL is provided in the request (duration string)
credentials.derived_tokens.jwt.signing_key_id	string	""	CREDENTIALS_DERIVED_TOKENS_JWT_SIGNING_KEY_ID	Optional JWK 'kid' hint used to select the active signing key.
credentials.derived_tokens.jwt.signing_keys.urls	string[]	[]	CREDENTIALS_DERIVED_TOKENS_JWT_SIGNING_KEYS_URLS	List of JWKS resources.
credentials.derived_tokens.macaroon.prefix.current	string	mc	CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_CURRENT	Current prefix used for new macaroon token generation.
credentials.derived_tokens.macaroon.prefix.retired	string[]	[]	CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_RETIRED	Retired prefixes accepted during macaroon verification for rotation purposes.
credentials.issuer	string	—	CREDENTIALS_ISSUER	Token issuer (iss claim) for derived tokens. (min 1 chars)
credentials.issuer_retired	string[]	[]	CREDENTIALS_ISSUER_RETIRED	Retired issuer URLs accepted during token verification.

db (restart required)

Database configuration.

Key	Type	Default	Env Var	Description
db.dsn	string	—	DB_DSN	Database connection string with scheme and optional query parameters. (restart required, min 1 chars)

last_used (restart required)

Configuration for batched last_used_at timestamp updates.

Key	Type	Default	Env Var	Description
last_used.flush_interval	string	30s	LAST_USED_FLUSH_INTERVAL	Maximum time between batch flushes (Go duration string, e.g. '30s', '1m'). (restart required)
last_used.flush_size	integer	100	LAST_USED_FLUSH_SIZE	Number of updates per shard that triggers a batch flush. (restart required)
last_used.num_workers	integer	4	LAST_USED_NUM_WORKERS	Number of goroutines processing last-used batches. (restart required)
last_used.queue_size	integer	10000	LAST_USED_QUEUE_SIZE	Buffer size for the async last-used update queue. (restart required)

log (restart required)

Logging configuration.

Key	Type	Default	Env Var	Description
log.format	json, text	json	LOG_FORMAT	Log format. (restart required)
log.level	debug, info, warn, error	info	LOG_LEVEL	Log level. (restart required)

multitenancy Commercial (restart required)

Multi-tenancy configuration.

Key	Type	Default	Env Var	Description
multitenancy.enabled	boolean	false	MULTITENANCY_ENABLED	Enable multi-tenancy support. (restart required, Commercial)
multitenancy.networks	object[]	[]	MULTITENANCY_NETWORKS	Network routing configuration. (restart required, Commercial)

quota

Resource caps for the current subscription tier.

Key	Type	Default	Env Var	Description
quota.api_keys_max	integer	—	QUOTA_API_KEYS_MAX	Maximum number of non-revoked API keys (issued + imported) the tenant may hold.

rate_limit Commercial

Rate limit enforcement for API keys with a RateLimitPolicy.

Key	Type	Default	Env Var	Description
rate_limit.backend	memory, redis	memory	RATE_LIMIT_BACKEND	Counter backend. (restart required, Commercial)
rate_limit.enabled	boolean	false	RATE_LIMIT_ENABLED	Enable rate limit enforcement. (Commercial)

secrets

Centralized secrets management.

Key	Type	Default	Env Var	Description
secrets.hmac.current	string	—	SECRETS_HMAC_CURRENT	Current HMAC secret for new key generation and checksum verification. (min 32 chars)
secrets.hmac.retired	string[]	[]	SECRETS_HMAC_RETIRED	Retired HMAC secrets that remain valid for verification during rotation

serve

Server configuration for HTTP and metrics endpoints.

Key	Type	Default	Env Var	Description
serve.http.client_ip_source	CLIENT_IP_SOURCE_UNSPECIFIED, CLIENT_IP_SOURCE_REMOTE_ADDR, CLIENT_IP_SOURCE_CF_CONNECTING_IP, CLIENT_IP_SOURCE_X_FORWARDED_FOR, CLIENT_IP_SOURCE_X_REAL_IP, CLIENT_IP_SOURCE_TRUE_CLIENT_IP	CLIENT_IP_SOURCE_UNSPECIFIED	SERVE_HTTP_CLIENT_IP_SOURCE	Determines which HTTP header or connection property is used to resolve the client IP for IP restriction checks. Must match your infrastructure topology. Default (unspecified) uses the TCP remote address. Hot-reloadable: read dynamically per request.
serve.http.cors.allow_credentials	boolean	false	SERVE_HTTP_CORS_ALLOW_CREDENTIALS	Indicates whether the request can include user credentials like cookies, HTTP authentication or client side SSL certificates.
serve.http.cors.allowed_headers	string[]	["Authorization","Content-Type"]	SERVE_HTTP_CORS_ALLOWED_HEADERS	A list of non simple headers the client is allowed to use with cross-domain requests. (min 1 chars)
serve.http.cors.allowed_methods	string[]	["GET","POST","PUT","PATCH","DELETE"]	SERVE_HTTP_CORS_ALLOWED_METHODS	A list of methods the client is allowed to use with cross-domain requests.
serve.http.cors.allowed_origins	string[]	["*"]	SERVE_HTTP_CORS_ALLOWED_ORIGINS	A list of origins a cross-domain request can be executed from.
serve.http.cors.debug	boolean	false	SERVE_HTTP_CORS_DEBUG	Set to true to debug server side CORS issues.
serve.http.cors.enabled	boolean	false	SERVE_HTTP_CORS_ENABLED	If set to true, CORS will be enabled and preflight-requests (OPTION) will be answered.
serve.http.cors.exposed_headers	string[]	["Content-Type"]	SERVE_HTTP_CORS_EXPOSED_HEADERS	Indicates which headers are safe to expose to the API of a CORS API specification (min 1 chars)
serve.http.cors.max_age	number	0	SERVE_HTTP_CORS_MAX_AGE	Indicates how long (in seconds) the results of a preflight request can be cached.
serve.http.host	string	0.0.0.0	SERVE_HTTP_HOST	The host (interface) that the endpoint listens on. (restart required)
serve.http.port	integer	4420	SERVE_HTTP_PORT	The port that the endpoint listens on. (restart required)
serve.http.request_log.exclude_health_endpoints	boolean	false	SERVE_HTTP_REQUEST_LOG_EXCLUDE_HEALTH_ENDPOINTS	Exclude /health/alive and /health/ready endpoints from request logs
serve.http.trust_forwarded_host	boolean	false	SERVE_HTTP_TRUST_FORWARDED_HOST	Trust the X-Forwarded-Host header for tenant routing. (restart required)
serve.metrics.host	string	0.0.0.0	SERVE_METRICS_HOST	The host (interface) that the metrics endpoint listens on. (restart required, Commercial)
serve.metrics.port	integer	4422	SERVE_METRICS_PORT	The port that the metrics endpoint listens on. (restart required, Commercial)

tracing Commercial (restart required)

OpenTelemetry tracing configuration.

Key	Type	Default	Env Var	Description
tracing.enabled	boolean	false	TRACING_ENABLED	Enable tracing. (restart required, Commercial)
tracing.endpoint	string	—	TRACING_ENDPOINT	Trace collector endpoint. (restart required, Commercial)
tracing.environment	string	development	TRACING_ENVIRONMENT	Deployment environment tag in trace attributes. (restart required, Commercial)
tracing.exporter	otlp	—	TRACING_EXPORTER	Trace exporter type. (restart required, Commercial)
tracing.sample_rate	number	0.001	TRACING_SAMPLE_RATE	Sampling rate (0.0 to 1.0). (restart required, Commercial)
tracing.service_name	string	talos	TRACING_SERVICE_NAME	Service name reported to OpenTelemetry. (restart required, Commercial)
tracing.service_version	string	0.0.0	TRACING_SERVICE_VERSION	Service version reported to OpenTelemetry. (restart required, Commercial)