Configuration reference

Flat, alphabetised reference. Every field TIM accepts in tim.yaml, its type, its default, and one line about what it does. For a walk-through with examples, see Configuration.

server

FieldTypeDefaultDescription
server.bindstring"0.0.0.0"Bind address.
server.portu168085TCP listener port.
server.max_request_bytesusize1048576Global request body cap.
server.request_timeout_secondsu6430Per-request deadline.
server.public_base_urlstring""Externally-reachable base URL; used to synthesise the default OAuth2 callback.

database

FieldTypeDefaultDescription
database.url_envstring"TIM_DATABASE_URL"Env var name holding the postgres:// URL.
database.min_connectionsu322Pool floor.
database.max_connectionsu3210Pool ceiling.
database.auto_migratebooltrueRun sqlx::migrate! at startup.
database.acquire_timeout_secondsu6430Pool acquire timeout (0 = sqlx default).
database.idle_timeout_secondsu64600Idle-connection reaper (0 = sqlx default).
database.max_lifetime_secondsu641800Connection max lifetime (0 = sqlx default).

Connections are .test_before_acquire(true) — a stale connection after a PgBouncer bounce is refreshed transparently.

jwt

FieldTypeDefaultDescription
jwt.private_key_pathpath"/opt/tim/keys/jwt-private.pem"PKCS#8 PEM RSA private key.
jwt.key_idstring"tim-rs-1"kid advertised in JWS headers + JWKS.
jwt.issuerstring"TIM"iss claim on every issued token.
jwt.audience.validation_enabledboolfalseIf true, POST /jwt/custom/generate rejects unlisted audiences.
jwt.audience.allowedlist[]Allow-list when validation is enabled.
jwt.audience.defaultstring"tim-service"Fallback aud when the caller omits one.
jwt.max_claims_bytesusize32768Cap on custom claim payload size at generate time.
jwt.bulk_revoke_maxusize100Max tokens per /jwt/custom/revoke/bulk call.
jwt.cookie_namestring"jwt"Cookie name used by the legacy compat endpoints.
jwt.rotation_warn_daysu327Days-before-retirement window at which boot emits a WARN that the previous key is approaching its cliff.
jwt.previous_keyobject(unset)Optional predecessor key retained during a rotation grace period. Signing always uses the current key; verifiers accept either while retires_at > now. See "Rotating the JWT signing key" below.

jwt.previous_key

Set together with jwt.private_key_path when rotating the JWT signing key. All three fields are required when the block is present.

FieldTypeDescription
.private_key_pathpathPKCS#8 PEM path of the retiring key.
.key_idstringkid under which the retiring key was advertised. MUST differ from jwt.key_id.
.retires_atRFC 3339Instant past which the previous key is refused on verification and dropped from JWKS.

Rotation flow:

  1. Generate a new PKCS#8 PEM. Add jwt.previous_key pointing at the OLD path + kid, set retires_at some days in the future (long enough for every downstream verifier to refresh its JWKS cache). Repoint jwt.private_key_path + jwt.key_id at the NEW key.
  2. Deploy TIM. GET /jwt/keys/public now returns both keys; all in-flight tokens continue to verify. New signatures use the new key.
  3. On or after retires_at, the previous key is no longer accepted and is dropped from JWKS. Delete the jwt.previous_key block on the next deploy to clean up.

Boot emits WARN when retires_at is within jwt.rotation_warn_days days. tim doctor reports the same via a jwt.previous_key check row.

oauth2

FieldTypeDefaultDescription
oauth2.session_storestring"memory""memory" or "postgres"; anything else fails at startup.
oauth2.discovery_cache_ttl_secondsu643600OIDC discovery cache TTL per provider.
oauth2.session_ttl_secondsu6486400Hard cap on session lifetime.
oauth2.session_sweep_interval_secondsu6460Background sweeper interval; 0 disables.
oauth2.state_max_age_secondsu64300Max age of an auth.oauth_state row at callback time.
oauth2.session_encryption_key_envstring"TIM_SESSION_ENCRYPTION_KEY"Env var holding the 32-byte hex AEAD key; required when session_store: "postgres".
oauth2.providersmap{}Provider ID → provider config.

oauth2.providers.<id>

FieldTypeDefaultDescription
.namestring(required)Human label.
.discovery_urlstring(required).well-known/openid-configuration URL.
.client_id_envstring(required)Env var name holding the client ID.
.client_secret_envstring(required)Env var name holding the client secret.
.scopeslist["openid","profile","email"]Scopes to request.
.claim_mappingsmap<string,string>{}<canonical> → <IdP claim>.
.token_validation.clock_skew_secondsu6460Leeway for exp, nbf, iat.
.token_validation.cache_ttl_secondsu643600JWKS cache TTL.
.allowed_redirect_urislist[]Allow-list of redirect_uri values. Empty = only the synthesised default.

security

FieldTypeDefaultDescription
security.admin_token_envstring""Env var name holding the admin token.
security.require_admin_tokenbooltrueRefuse boot when admin_token_env is set but empty.
security.cors_allowed_originslist[]CORS origins. ["*"] for wildcard; empty = no CORS layer.
security.content_security_policystring"default-src 'none'; frame-ancestors 'none'"CSP header. Empty = skip.
security.strict_transport_securitystring"max-age=63072000; includeSubDomains"HSTS header. Empty = skip.
security.referrer_policystring"no-referrer"Referrer-Policy header.
security.x_frame_optionsstring"DENY"X-Frame-Options header.
security.x_content_type_optionsstring"nosniff"X-Content-Type-Options header.

Command-line + env

SourcePurpose
--config <path>Explicit config path.
TIM_CONFIGSame, via env.
RUST_LOGtracing_subscriber EnvFilter (info, debug, tim=debug,sqlx=warn).

Startup-refusal matrix

Startup fails hard when:

  • database.url_env env var is unset.
  • security.require_admin_token: true and admin_token_env is unset or its target env var is empty.
  • oauth2.session_store: "postgres" and session_encryption_key_env is empty or the target env var is malformed hex / not 32 bytes.
  • oauth2.session_store is anything other than "memory" or "postgres".
  • Any provider's client_id_env or client_secret_env target is unset.
  • The JWT private key PEM is unreadable or not PKCS#8.
  • Migrations fail (with auto_migrate: true).