Skip to main content
Version: 5.x

Configure the plugin

Just like any other plugin in Strapi, Headlockr requires some default configuration in order to get it up and running. Most of the required environment variables are autogenerated by Headlockr the first time you start up Headlockr. The only required environment variable is HEADLOCKR_LICENSE_KEY. Please follow the tutorial at the next chapter on how to set this up.

Headlockr Config file​

Headlockr comes with the default configuration file below which can be overwritten. However, we must warn you that doing so might break the plugin. So please use with caution!

If you'd like to overwrite the default configuration, create a new file or edit your existing plugins config file located at ./config/plugins.js|ts

danger

Please be aware that disabling headlockr and enabling it afterwards will wipe all your previous saved data from the database. This is something that we do not have control over since this is happening from within the Strapi Core.

  headlockr: {
    enabled: true, // ❗️ Caution: disabling the plugin will wipe previous data from the database.
    config: {
      // Optionally: Headlockr will cleanup any expired otp codes that were generated by it recurringly.
      cron: {
        enabled: true,
        schedule: "0 0 * * *", // This will run the cron job every day at midnight. Any Cron expression can we used here.
      },
      licenseKey: env("HEADLOCKR_LICENSE_KEY"), // Your license key that you received from us
      auth: {
        encryptionIv: env("ENCRYPTION_IV_HEADLOCKR"), // A random 32 bytes long base64 string *
        encryptionKey: env("ENCRYPTION_KEY_HEADLOCKR"), // A random 16 bytes long base64 string *
        backupEncryptionIv: env("ENCRYPTION_IV_HEADLOCKR_BACKUP"), // *
        backupEncryptionKey: env("ENCRYPTION_KEY_HEADLOCKR_BACKUP"), // *
        secret: env("MFA_SECRET"), // This is the secret used to sign the shortlived tokens
        phoneTokenSecret: env("PHONE_TOKEN_SECRET"), // This is the secret used to sign the phone tokens that are used during phone registration of a user
        // Any option that jwt supports
        options: {
          expiresIn: "5m",
          audience: "strapi-admin-panel",
          issuer: "headlockr-admin-auth",
        },
      },
       twilio: {
        accountSid: env("TWILIO_ACCOUNT_SID"),
        apiKeySid: env("TWILIO_API_KEY_SID"),
        apiKeySecret: env("TWILIO_API_KEY_SECRET"),
        from: env("TWILIO_PHONE_NUMBER"),
      },
      cookies: {
        httpOnly: false,
        secure: process.env.NODE_ENV === "production",
        sameSite: "Lax",
        //maxAge: 1000 * 60 * 5, // 5 minutes
        path: "/",
      },
    },
  },

New in Headlockr 5​

Passkeys​

Headlockr now supports passkey-based authentication. The passkeys config controls:

  • rpId: the relying party ID used for passkey registration and login
  • rpName: the label shown to users during passkey flows
  • origins: allowed origins for passkey verification
  • magicLogin.enabled: enables the QR-based companion app login flow
  • webLogin.enabled: enables browser-native passkey login

If you enable passkeys, make sure HEADLOCKR_PASSKEY_RP_ID and HEADLOCKR_PASSKEY_ORIGINS match your real environment.

Trusted devices​

Trusted devices let users reduce MFA prompts on known devices after a successful login.

  • enabled: turns the feature on or off
  • ttlMs: how long a device remains trusted
  • cookieName: cookie name used for the trusted-device token
  • secret: signing secret for trusted-device cookies
  • requireRememberMe: only trusts a device when the user explicitly opts in

If HEADLOCKR_TRUSTED_DEVICE_SECRET is omitted, Headlockr falls back to MFA_SECRET.

Required environment variables​

Headlockr still autogenerates most encryption and token secrets on first boot when they are missing. In practice, the values you usually need to provide yourself are:

  • HEADLOCKR_LICENSE_KEY
  • HEADLOCKR_PASSKEY_RP_ID when using passkeys
  • HEADLOCKR_PASSKEY_ORIGINS when using passkeys
  • Twilio credentials when using SMS