Configuration¶

Freebird reads configuration from environment variables. This page lists the settings needed to understand the local flow and the production baseline; it is not an exhaustive environment-variable reference. Defaults and requirements describe the V4 services and production baseline.

Common service settings¶

Variable	Purpose
`ADMIN_API_KEY`	Mandatory admin authentication key for both services; it must be at least 32 characters.
`BIND_ADDR`	Service listen address (`0.0.0.0:8081` issuer, `0.0.0.0:8082` verifier by default).
`REQUIRE_TLS`	Enforce HTTPS at the trusted proxy boundary; use `false` only for deliberate local development.
`BEHIND_PROXY`	Enables the trusted-proxy handling used with forwarded request metadata.

Production should set REQUIRE_TLS=true, configure BEHIND_PROXY and trusted proxy CIDRs, and expose the services only through an independently managed HTTPS reverse proxy. Compose's direct local HTTP mode does not satisfy this baseline.

Issuer settings¶

Variable	Purpose
`ISSUER_ID`	Issuer namespace embedded in metadata and issued material.
`ISSUER_SK_PATH`	Persistent V4 issuer secret-key path.
`KEY_ROTATION_STATE_PATH`	V4 key-rotation state path.
`KID`	Optional V4 KID compatibility override. The default is derived only from the persisted issuer key and is stable across restarts and UTC date changes; an override is preserved only when it begins with that derived KID, otherwise startup falls back to the derived KID. Rotation metadata must contain the same active KID and supported state version or startup fails; retain a legacy override while retaining matching legacy rotation state.
`SYBIL_RESISTANCE`	Admission mode; use an explicit mode, and do not use `none` for a public issuer.
`SYBIL_REPLAY_STORE`	Replay backend for applicable Sybil proofs; use `redis` for restart-safe/public multi-instance operation.
`SYBIL_REPLAY_REDIS_URL`	Redis URL for that Sybil replay backend; it can fall back to `REDIS_URL`.

V4 verification continues to use strict exact-KID lookup. The intentional legacy migration path is to set KID to the former date-suffixed value when it begins with the persisted key's derived KID and retain that override while the matching legacy rotation-state file is retained. To omit KID, explicitly reset/delete the rotation-state file first; this accepts an identity transition to the stable key-derived identity.

WebAuthn additionally requires WEBAUTHN_RP_ID, WEBAUTHN_RP_ORIGIN, and a high-entropy WEBAUTHN_PROOF_SECRET. The origin must match the browser origin; production should use HTTPS.

Verifier settings¶

Variable	Purpose
`VERIFIER_ID`	Required verifier identity; V4 tokens bind to its scope.
`VERIFIER_AUDIENCE`	Audience in the verifier scope; defaults to the verifier ID.
`ISSUER_URL` / `ISSUER_URLS`	V4 issuer metadata URL(s); HTTPS is required when TLS enforcement is enabled.
`REDIS_URL`	Verifier replay/nullifier store outside explicit development memory mode.
`VERIFIER_ENV` and `IN_MEMORY_REPLAY_STORE`	The explicit development-only opt-in for an in-memory replay store.
`VERIFIER_SK_PATH`	V4 private verification key.
`REFRESH_INTERVAL_MIN`	Issuer metadata refresh interval.

Production storage baseline¶

Production requires durable Redis for verifier replay protection and issuer Sybil replay state, plus persistent protected storage for issuer keys and audit logs. Do not use IN_MEMORY_REPLAY_STORE=true in production.

Keep keys at restrictive filesystem permissions, back up Redis and related key and audit data as one coherent recovery unit, and run the configuration validator against the exact production environment. See Production Deployment for the complete baseline and Admin Operations for operator controls.