# AUTH_SECRET and production fail-fast

URL: https://kywi-docs-production.up.railway.app/operating/authsecret-and-production-fail-fast
Type: docPage

Kywi refuses to start in production when AUTH_SECRET is missing or set to one of two known dev fallbacks, because tokens signed with it would be forgeable.

This is the message, and it is fixed — there is no variant, so it is worth recognising on sight in a deploy log:

AUTH_SECRET is not set (or is the insecure dev fallback) in production. Set a strong random secret before deploying: export AUTH_SECRET=$(openssl rand -base64 32) Refusing to start: tokens signed with a known secret can be forged.

## the refusal, verbatim

Run that `openssl` line, set the result on the service, and deploy again. The first deploy of this documentation's own host failed here and nowhere else.

## What counts as insecure

Exactly three cases: missing, empty, or equal to one of two literals — `dev-secret` and `dev-secret-change-in-production`. Every other non-empty string passes. There is no length check, no entropy check, and no character class requirement anywhere in the policy, so `AUTH_SECRET=x` starts a production deploy cleanly. The assertion is a floor against the two placeholders that ship in scaffolds and docs, not a strength meter.

## It fails at module scope, so it looks like a build failure

The assertion runs at import, in two places. Core's middleware calls it at the top level of the edge bundle, and the generated `kywi.config.ts` calls it again on its own first line. So a production `next build` or `next start` is what breaks — no request is ever served with a bad secret, and there is no half-working state to debug. The config copy has a second consequence operators hit later: `kywi migrate` and `kywi seed` import that config too, so a CLI run with `NODE_ENV=production` and no secret refuses for the same reason, on a machine where the only intent was to touch the database.

## A staging box left at NODE_ENV=development is the real hazard

The gate is `NODE_ENV === 'production'` and nothing else. Below it the same missing secret is downgraded to one warning line — `[kywi] AUTH_SECRET is not set — using an INSECURE development fallback. Set AUTH_SECRET to a strong random value before deploying to production.` — and the process starts anyway, signing real session tokens with a string published in this documentation. Anyone can mint an admin session against that host. Staging counts as production for this variable; set both `NODE_ENV` and `AUTH_SECRET` on every deployed environment.

## Rotating it

The secret signs session JWTs, so changing it invalidates every issued session at once: every logged-in person is signed out on their next request, and there is no grace period or dual-secret verification. There is nothing to run afterwards — the new value takes effect when the process restarts with it. In development the same resolver does not rotate anything on its own: an explicitly set `AUTH_SECRET`, dev fallback or not, is kept as-is on every resolve — the built-in `dev-secret-change-in-production` value only fills in when the variable is unset entirely.

API keys are unaffected. A token beginning `kywi_` is resolved against the database and returns before the signature path is reached, so it never touches the secret. Cron jobs, CI runners, page scripts and anything else authenticating with a key keep working across a rotation — which also means rotating the secret is *not* a way to cut off a leaked key. That is a key revocation, and the key's scopes cap what it could do in the first place ([API keys: scopes are a role ceiling](/agent/api-keys-scopes-are-a-role-ceiling/)).

Where this assertion sits among the other things that can fail a boot is [Startup assertions](/developing/startup-assertions--the-config-errors-that-fail-a-deploy/); the rest of the deploy environment is [Deploying a host app](/operating/deploying-a-host-app/).
