Skip to main content
Version: 5.x

OTP / TOTP Rotation & Account Lockout

⚠️ Important: Persist Headlockr Environment Variables​

Headlockr automatically generates several security-related environment variables on first boot and injects them into your local .env file. You'll have to spin up Headlockr in your local environment first to get those variables.

These variables are used to sign and validate OTP/TOTP secrets.

What can go wrong?​

If you deploy your project to production without copying these generated environment variables, Headlockr will generate new ones on every fresh deploy or container restart.

When that happens:

  • Previously registered OTP/TOTP secrets can no longer be validated since the secret rotated
  • Login attempts will fail
  • Your admin account could become locked out

This commonly occurs when:

  • Deploying to a new production server
  • Using Docker without persisting environment variables
  • Running stateless containers
  • Rebuilding infrastructure without copying secrets

✅ What you must do​

After first boot in your local environment:

  1. Locate the environment variables generated by Headlockr in your .env file.
  2. Copy all generated Headlockr-related variables to your production environment.
  3. If you are using Docker, define them:
    • In your docker-compose.yml
    • As container environment variables
    • Or inside your secret manager (depending on your infrastructure)

These values must remain stable across deployments.

🔁 If You Are Already Locked Out​

If the variables were rotated and you can no longer log in, the only way to recover access is:

  1. Redeploy your application with Headlockr temporarily disabled
  2. This clears the related security data from the database
  3. Immediately redeploy again with Headlockr enabled

This resets the OTP/TOTP configuration and allows you to log in again. In the future there will be a CLI that allows an administrator to recover accounts via the terminal.

🔐 Best Practice​

Treat Headlockr-generated environment variables like any other secret:

  • Store them in a secure secret manager
  • Keep them consistent across environments
  • Never allow them to rotate unintentionally